> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upmind.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upmind API - Affiliate Cookie Flow

> Integrate affiliate tracking with Upmind.

# Affiliate link and referral cookie flow

This guide explains how to integrate affiliate tracking with Upmind when building a custom client area. It covers:

1. Affiliate link visits

2. Referral signups

3. Referral orders

The same flow applies whether you use Upmind’s first-party affiliate system, Post Affiliate Pro integration, or both.

## Core concept

`referral_cookie` is an opaque, encrypted string used by the affiliate abstraction layer. Your frontend should:

1. Send it when available

2. Store any updated value returned by the API

3. Re-send it on registration and order conversion requests

Do not attempt to parse, modify, or en/decode `referral_cookie`; treat it as a transport value.

### Post Affiliate Pro

When PAP is configured in your Brand’s settings, the **click** data will be sent to PAP’s tracking URL, and the `referral_cookie` will contain the visitorId, which PAP uses to correlate link clicks with conversions. Typically, PAP affiliate links can be identified by the presence of an affiliate ID in the query string, e.g. `?aid=abc123`.

## End-to-end flow

1. The visitor lands on an affiliate URL.

2. Frontend calls `POST /api/affiliate_link/visit` with visit metadata and existing `referral_cookie` (if present).

3. API responds with `redirect_url` and optionally a refreshed `referral_cookie` (+ max age).

4. Frontend sets/updates the browser cookie and redirects the visitor.

5. When the visitor registers (e.g. `/api/clients/register`), send `referral_cookie`.

6. When converting basket to invoice (`/api/orders/<order_id>/convert`), send `referral_cookie` again.

This ensures referral attribution can be linked from click > signup > paid order.

## API 1: Track affiliate link visit

Endpoint:

* `POST https://api.upmind.io/api/affiliate_link/visit`

**Remember to include your Upmind domain in the Origin header so we can determine the correct brand + settings context.**

**Example**: `Origin: https://xyz.upmind.app`

Request body fields:

* `visit_url` (required): Full current browser URL, including query string and hash.

  * To configure the onward redirect for Post Affiliate Pro links, it’s possible to add a \&redirect=

    parameter to affiliate links; ensure this is included in `visit_url` for this to be returned as `redirect_url` in the response. As long as the redirect URL is on the same domain as the visit URL or is added in your Upmind brand’s domain settings, it will be permitted as a redirect target; otherwise, your configured default redirect URL will be used; this is a security measure to prevent malicious redirects.

* `referrer_url` (required): Browser referrer URL.

* `user_agent` (required): Browser user agent string.

* `referral_cookie` (optional): Existing referral cookie value, if already present.

Example request:

<CodeGroup>
  ```json JSON theme={null}
  {
    "visit_url": "https://example.com/?aid=abc123&utm_source=partner&redirect=https%3A%2F%2Fexample.com%2Fproducts",
    "referrer_url": "https://partner.example.net/review-page",
    "user_agent": "Mozilla/5.0 (...) Safari/537.36",
    "referral_cookie": "<existing-cookie-if-any>"
  }
  ```
</CodeGroup>

Example success payload:

<CodeGroup>
  ```json JSON theme={null}
  {
    "data": {
      "redirect_url": "https://example.com/products",
      "referral_cookie": "<new-or-updated-cookie>",
      "referral_cookie_max_age": 2592000
    }
  }
  ```
</CodeGroup>

Client handling rules:

1. If `data.referral_cookie` exists, set/update a first-party cookie in the browser.

2. Use `data.referral_cookie_max_age` as the cookie lifetime when present.

3. Redirect the visitor to `data.redirect_url`.

## API 2: Send referral cookie during client registration

Supported registration endpoints:

* `POST /api/clients/register` - Standard client registration endpoint

* `POST /api/clients/register/guest` - Guest client creation endpoint for basket operations

* `POST /api/clients/<client_id>/complete_registration` - Guest registration completion endpoint

Payload field:

* `referral_cookie` (optional): Pass the current cookie value from the browser.

Example standard registration payload excerpt:

<CodeGroup>
  ```json JSON theme={null}
  {
    "email": "customer@example.com",
    "firstname": "Alex",
    "lastname": "Doe",
    "password": "<redacted>",
    "referral_cookie": "<cookie-from-visit-step>",
    "user_agent": "Mozilla/5.0 (...) Safari/537.36"
  }
  ```
</CodeGroup>

## API 3: Send referral cookie when converting basket to order invoice

Endpoint:

* `PATCH /api/orders/<order_id>/convert`

Payload field:

* `referral_cookie` (optional): Pass the current cookie value so the order referral can be associated.

Example request:

<CodeGroup>
  ```json JSON theme={null}
  {
    "payment_details_id": 12345,
    "referral_cookie": "<cookie-from-visit-step>"
  }
  ```
</CodeGroup>

Why this matters:

* The referral cookie is stored against the initial order invoice and later used to record the affiliate sale after payment is made.

## Recommended integration pattern (Frontend)

1. On every page load where affiliate params may be present, call `/api/affiliate_link/visit`.

2. Always include the current cookie value in that call when available.

3. Persist returned cookie as a first-party cookie.

4. Include cookie value in:

   * `/api/clients/register` or `/api/clients/register/guest` or `/api/clients/<client_id>/complete_registration`

   * `/api/orders/<order_id>/convert`

5. Do not attempt to modify cookie contents in frontend code.

## Implementation checklist

* Capture and send `visit_url`, `referrer_url`, `user_agent` on link visit

* Persist returned `referral_cookie`

* Pass `referral_cookie` during registration

* Pass `referral_cookie` during basket conversion

* Allow graceful behaviour if the cookie is absent