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:

Example
JSON
Copy
{
  "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>"
}

Example success payload:

Example
JSON
Copy
{
  "data": {
    "redirect_url": "https://example.com/products",
    "referral_cookie": "<new-or-updated-cookie>",
    "referral_cookie_max_age": 2592000
  }
}

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:

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

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:

Example
JSON
Copy
{
  "payment_details_id": 12345,
  "referral_cookie": "<cookie-from-visit-step>"
}

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 behavior if the cookie is absent