Skip to main content
POST /api/checkout/start accepts a tracking object. UnderPass stores it with the order and uses it for two things: campaign attribution in the organizer’s reports, and server-side matching of the conversion on Meta (Conversions API) and TikTok (Events API). Everything in it is optional; send what you have.

​
Capture rules

  • First touch wins. Read utm_*, gclid, fbclid, ttclid, document.referrer and the full landing URL on the buyer’s first page view of the session, store them (a cookie or sessionStorage), and keep them even if a later page carries different parameters. A mid-session UTM must not hijack the attribution.
  • ttclid arrives as ?ttclid= on TikTok ad clicks. Keep it 30 days (TikTok’s attribution window). ttp is the value of the _ttp cookie the TikTok pixel sets; read it at submit.
  • fbc / fbp are the Meta cookies (_fbc, _fbp); read them at submit. If you have an fbclid but no _fbc cookie, build it as fb.1.<timestamp ms>.<fbclid>.
  • channel is your derived bucket (paid_social, organic_search, direct, …). Optional; UnderPass derives one too when it is missing.
  • client_ip_address should be the buyer’s real IP. If your storefront calls the API from a server, forward the IP from your edge (cf-connecting-ip, x-real-ip, or the first x-forwarded-for hop). Private or loopback addresses are worse than none.
  • client_user_agent is navigator.userAgent, or the request header when called server-side.

​
Why it matters

The same order fires a browser pixel event and a server-side event on both ad platforms, deduplicated by the order id (see Analytics pixels). The server-side event can only be matched to the ad click through fbc / fbp / ttclid / ttp, the IP and the user agent. Orders without them still count in your reports, but the ad platform may not credit the campaign.