Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. API Reference
  3. Affiliate
  4. Start Journey

Start Journey

POST https://api.firmly.work/api/v1/carts/affiliate/start-journey

​​ Overview

Start Journey is the BYO (Bring Your Own Link) endpoint. It resolves the partner-supplied affiliate link, captures the attribution details, and stores them in the device session. The response returns the resolved merchant URL, network, and click identifier.

​​ Integration rules

  • Call once, as early as practical, when the shopper arrives after clicking an affiliate link.
  • Send the affiliate link itself as the url value. Start Journey follows it to resolve the merchant page and attribution details.
  • Do not call it for managed attribution or ordinary, non-affiliate landings.
  • Do not retry blindly; repeating the request can register the click again.
  • Treat the journey as attributed only when both network and click_id are present. success alone is not an attribution signal.

​​ Authentication

Establish a device session using Browser Session before calling Start Journey. Partner integrations enabled by Firmly should send the resulting token in x-firmly-authorization; Firmly-hosted surfaces may use their established browser session.

x-firmly-authorization (string, required) — device authentication token identifying the shopping session.

​​ Request

Send a JSON body with Content-Type: application/json. The url field is the affiliate link supplied by the partner.

url (string, required) — the affiliate link to resolve. Send the original tracking link, not the merchant page URL after the link has been followed.

​​ Request Example 


curl --request POST \
  --url https://api.firmly.work/api/v1/carts/affiliate/start-journey \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"url":"https://www.anrdoezrs.net/click-100-15?url=https%3A%2F%2Fmerchant.example%2Fproduct%2F123"}'

​​ Response

When processing completes normally, the response contains:

Field Type Meaning
success boolean true when a final merchant URL was resolved. This does not mean attribution was captured or commission will be approved.
network string or null Detected affiliate network, or null when none was detected.
click_id string or null Affiliate click identifier, or null when none was found. Treat the journey as attributed only when both network and click_id are non-null.
buyer_id string or null Network-provided visitor identifier, when available. Informational only.
sub_affiliate string or null Content-monetization service identified at the start of the link chain, when applicable. Informational only.
final_url string or null Final merchant URL reached from the supplied URL, or null when no merchant page was resolved.

​​ Response Example 


{
  "success": true,
  "network": "cj",
  "click_id": "abc123def456",
  "buyer_id": null,
  "sub_affiliate": null,
  "final_url": "https://merchant.example/product/123"

}

​​ No attribution detected

The merchant page resolved, but the URL did not contain a supported attribution signal:


{
  "success": true,
  "network": null,
  "click_id": null,
  "buyer_id": null,
  "sub_affiliate": null,
  "final_url": "https://merchant.example/product/123"

}

​​ Degraded response

If the downstream attribution service returns a non-success or unreadable response, Start Journey returns a smaller best-effort result:


{
  "success": false,
  "network": null,
  "click_id": null,
  "final_url": null

}

buyer_id and sub_affiliate are omitted from this degraded shape. Transport, session, validation, and other unexpected failures can instead produce an HTTP error. If affiliate tracking fails, the shopper can still browse and complete checkout.

​​ Error responses

Status Error Meaning
400 InvalidInputBody url is missing, not a string, or the body is not valid JSON.
400 MissingAuthHeader / InvalidToken The device session credential is missing or malformed.
401 InvalidJWTToken The supplied device token failed verification or has expired.
404 PartnerNotFound The partner associated with the device credential could not be resolved.
404 DomainNotFound The resolved merchant is unavailable to the authenticated partner; attribution is not recorded.
500 Unexpected An unexpected service or session failure occurred. Do not automatically replay the affiliate URL.