Skip to content

Custom API

Checkout attribution

Reference only. Not a decision unless cited in product/DECISIONS.md.

Checkout attribution

Send purchase-source fields on order create so Attendees, sales insights, and analytics know where the sale happened. These fields are advisory — missing attribution never blocks order create or payment.

FieldExampleNotes
checkout_hostyoursite.comPrefer browser Origin / Referer; body host is a fallback
checkout_originhttps://yoursite.comFull origin when known
checkout_path/tickets?utm_source=newsOptional path and query string. Scrubbed before storage (see below)
checkout_surfacepartner_headlessOr partner_embed for Web SDK
checkout_integrationheadless_apiweb_sdk, mobile_sdk, or axyn_web
checkout_deviceios / android / desktopOptional; server may infer from User-Agent
checkout_utm_source / _medium / _campaignmarketing paramsOptional campaign tags
checkout_referrer_hostprior site hostOptional

What happens to checkout_path

Send the path and everything after the ?. That is where a link carries its campaign: tags and ad click references such as gclid and fbclid. The organizer sees it on the order and in the attendee export, so they can tell which promotion led to the sale.

AXYN scrubs it before storing, and the Web SDK scrubs it before sending:

  • the part after # is dropped
  • a value is kept only for a campaign parameter: utm_*, the tracking link axl, the click references gclid, fbclid, msclkid and ttclid, Mailchimp's campaign id mc_cid, and AXYN's own org and event
  • every other parameter keeps its name and loses its value. That includes the subscriber ids email tools add to each link (mc_eid, _kx, _hsenc, mkt_tok and the like), your own labels and discount codes
  • a campaign parameter named like identity or a secret (utm_email, utm_token) loses its value too
  • any value that looks like an email address or a written phone number is removed, whatever the parameter is called
  • addresses over 1,024 characters keep whole parameters from the front and end with axyn_cut=1

A value AXYN cannot read as a path is ignored; the order is still created.

Headless / Custom API

  • Forward browser Origin (and Referer when useful) on POST /v1/orders.
  • Or set body checkout_host / checkout_origin plus checkout_surface: "partner_headless" and checkout_integration: "headless_api" when Origin is unavailable (typical for server-side BFFs).
  • Optional BFF headers: x-axyn-checkout-origin, x-axyn-checkout-referer.
  • Do not stamp axyn.events or axyn_shop from a partner site.
  • Do not send tenant_id as authority — tenant comes from the API key.
  • AXYN does not treat X-Forwarded-Host (e.g. api.axyn.events) as the buyer checkout host — that is the API edge, not where the sale happened. Infra Origin/Referer (api.axyn.events) is treated as absent.
  • A tenant API key is tenant identity, not sale surface (ENG-1684). True partner Headless API (no AXYN Origin, no X-Axyn-Buyer-Surface: hosted) still defaults to partner_headless / headless_api. Host comes from Origin, x-axyn-checkout-origin, body checkout_host, or the tenant website_url commerce host. AXYN never invents api.axyn.events.
  • The same default applies to buyer-JWT checkout with no API key when it comes from your server: no body checkout_surface / checkout_integration, and either no Origin/Referer or the buyer's page forwarded in x-axyn-checkout-origin / x-axyn-checkout-referer. It is stamped partner_headless / headless_api with the forwarded host, else your website_url host.
  • Apple Pay / Google Pay (ENG-3259): every checkout that is not on AXYN's hosted pages registers your saved website (Settings › Profile website_url, the same host as above) for wallets on your payment account; for an example.com / www.example.com pair, the other one too (agent default pending ENG-3259 Q-W1). Nothing to send: buyer sign-in alone is enough. Only an https address on a real host counts (no http, localhost, IP, axyn.events or *.railway.app hosting host). A checkout host that is not your saved website needs your API key plus the page's Origin (or x-axyn-checkout-origin); a forwarded page address without the key is never registered. Up to 10 organizer sites per payment account.
  • A keyless call straight from a browser should send body checkout_surface (the Web SDK does). Without it AXYN infers the surface from the Origin and raises an alert.
  • checkout_device from a server User-Agent (node, axios, curl) is unknown, not desktop. Send body checkout_device or forward the buyer's User-Agent if you want the buyer's device recorded.
  • First-party hosted shop (Origin/x-axyn-checkout-origin on axyn.events, or X-Axyn-Buyer-Surface: hosted) keeps axyn_shop / axyn_hosted / axyn_web. The catalog key used by the AXYN BFF must not rewrite that to the organizer website_url (e.g. rotationnapa.com).
  • Hosted axyn.events payment after a partner start does not overwrite Headless API / Web SDK / a partner host with axyn_web.

Event views / Sales impressions (ENG-500)

Hosted shop and Web SDK embeds emit a first-party POST /v1/events/{eventId}/views beacon (opaque session_key, host, surface, integration). That fact is the impressions denominator for Sales CVR.

Headless: pageviews stay N/A until Partner page insights is on for the event and the commerce pixel is installed with Analytics consent. The pixel (GET /v1/commerce-pixel.js) posts the same allowlisted view body with checkout_surface: "partner_headless" and checkout_integration: "headless_api" — no browser API key (ENG-635). Without enable + install + consent, do not:

  • Call views ingest with checkout_integration: "headless_api" when the flag is off (422 pixel_disabled)
  • Invent a view from catalog GET or from order create
  • Expect impressions/CVR for headless — admin shows N/A for that integration
  • Put AXYN_API_KEY / data-axyn-api-key in page HTML

Paid-order attribution on order checkout_* fields still works for headless sales mix; only the pageview denominator is N/A until the pixel path above.

Channel and campaign from your order UTMs (ENG-2575). Send checkout_utm_source, checkout_utm_medium and checkout_utm_campaign on a Headless API order create (partner_headless / headless_api: your server on /v1, no Web SDK) and a paid order with no recorded visit is credited in the organizer's Overview → Conversion → Sources: under the channel a visit with the same tags would get (the same rule, utm_source and utm_medium read in lowercase) and under its campaign, marked "reported by the selling partner". It no longer counts as an untracked online order. Rules:

  • A source or a medium is needed: a campaign name alone names no channel, so that order stays untracked
  • A recorded visit (pixel, Web SDK, hosted page) always wins over the order's tags, and each order is counted once
  • Headless API orders only: the hosted shop and Web SDK embeds send checkout_utm_* too, but with no recorded visit (analytics declined, an ad blocker, analytics off) those orders stay untracked
  • Paid, reportable orders only, exactly as Sales counts them (test orders left out, refunds net)
  • It adds no view, funnel step or drop-off, no visitor and no buyer to any conversion rate, and no sales to sales per visitor. Device, place and where they bought still need a recorded visit
  • AXYN does not check the tags you send

Privacy / partner disclosure: partners who embed the Web SDK or the headless commerce pixel must disclose AXYN under Analytics cookies. Locked allowlist, denylist, and install snippet: Partner commerce insights & privacy.

See Headless API and Get started.

Web SDK embed

The SDK collects partner host + web_sdk automatically when the buyer checks out in an embed, and emits the Sales view beacon. Prefer the SDK path over hand-rolling body fields. Disclose per Partner commerce insights & privacy.

Mobile SDK (advisory)

FieldRecommended
checkout_integrationmobile_sdk
checkout_deviceios or android
checkout_hostYour app’s public host or brand domain when known
UTMsOptional campaign tags

Omitting these does not fail the sale. AXYN stores what it can. Paid tenant-key, SDK, and hosted checkout sales are not shown as Unknown on Sales (ENG-787). Optional campaign fields may still be empty.

What AXYN guarantees

  1. Best-effort stamp on create (and remint when columns are still empty).
  2. Never invent a partner domain or api.axyn.events as the buyer host.
  3. Never return attribution in the API as if it were persisted when the DB write failed.
  4. Never 4xx/5xx solely because attribution is incomplete.
  5. Tenant API key, or buyer-JWT checkout with no sale signal → Headless API unless the buyer is first-party hosted (X-Axyn-Buyer-Surface: hosted or AXYN checkout Origin). Web SDK / Mobile SDK body is kept. True hosted shop//checkout → AXYN web + axyn.events even when the BFF attaches a catalog API key.

Staging smoke (ENG-489, ENG-787)

Prove on staging (never production):

  1. Hosted — create order via web-axyn / axyn.events; expect checkout_host=axyn.events, checkout_integration=axyn_web when BFF forwards Origin.
  2. Embed — Web SDK partner embed; expect partner host + web_sdk.
  3. Headless with Origin — partner Origin or body host; expect partner_headless / headless_api + that host.
  4. Headless missing host — omit Origin and checkout_host; order create and pay still succeed; integration is headless_api; host is the tenant website_url host when set (never api.axyn.events). Logs/metrics may still show missing_host when no partner host is known.
  5. Stamp failure honesty — if stamp write fails, order still returns success without fabricated attribution fields that the DB lacks.

Unit guards: ticketing-service tests checkoutAttributionFailClosed, checkoutAttributionMetrics, checkoutAttribution resolver suite.