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.
Recommended fields (order create body or headers)
| Field | Example | Notes |
|---|---|---|
checkout_host | yoursite.com | Prefer browser Origin / Referer; body host is a fallback |
checkout_origin | https://yoursite.com | Full origin when known |
checkout_path | /tickets?utm_source=news | Optional path and query string. Scrubbed before storage (see below) |
checkout_surface | partner_headless | Or partner_embed for Web SDK |
checkout_integration | headless_api | web_sdk, mobile_sdk, or axyn_web |
checkout_device | ios / android / desktop | Optional; server may infer from User-Agent |
checkout_utm_source / _medium / _campaign | marketing params | Optional campaign tags |
checkout_referrer_host | prior site host | Optional |
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 linkaxl, the click referencesgclid,fbclid,msclkidandttclid, Mailchimp's campaign idmc_cid, and AXYN's ownorgandevent - 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_tokand 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(andRefererwhen useful) onPOST /v1/orders. - Or set body
checkout_host/checkout_originpluscheckout_surface: "partner_headless"andcheckout_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.eventsoraxyn_shopfrom a partner site. - Do not send
tenant_idas 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 topartner_headless/headless_api. Host comes from Origin,x-axyn-checkout-origin, bodycheckout_host, or the tenantwebsite_urlcommerce host. AXYN never inventsapi.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 inx-axyn-checkout-origin/x-axyn-checkout-referer. It is stampedpartner_headless/headless_apiwith the forwarded host, else yourwebsite_urlhost. - 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 anexample.com/www.example.compair, the other one too (agent default pending ENG-3259 Q-W1). Nothing to send: buyer sign-in alone is enough. Only anhttpsaddress on a real host counts (nohttp,localhost, IP,axyn.eventsor*.railway.apphosting host). A checkout host that is not your saved website needs your API key plus the page'sOrigin(orx-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_devicefrom a server User-Agent (node,axios,curl) isunknown, notdesktop. Send bodycheckout_deviceor forward the buyer'sUser-Agentif you want the buyer's device recorded.- First-party hosted shop (
Origin/x-axyn-checkout-originonaxyn.events, orX-Axyn-Buyer-Surface: hosted) keepsaxyn_shop/axyn_hosted/axyn_web. The catalog key used by the AXYN BFF must not rewrite that to the organizerwebsite_url(e.g. rotationnapa.com). - Hosted
axyn.eventspayment after a partner start does not overwrite Headless API / Web SDK / a partner host withaxyn_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
GETor from order create - Expect impressions/CVR for headless — admin shows N/A for that integration
- Put
AXYN_API_KEY/data-axyn-api-keyin 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)
| Field | Recommended |
|---|---|
checkout_integration | mobile_sdk |
checkout_device | ios or android |
checkout_host | Your app’s public host or brand domain when known |
| UTMs | Optional 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
- Best-effort stamp on create (and remint when columns are still empty).
- Never invent a partner domain or
api.axyn.eventsas the buyer host. - Never return attribution in the API as if it were persisted when the DB write failed.
- Never 4xx/5xx solely because attribution is incomplete.
- Tenant API key, or buyer-JWT checkout with no sale signal → Headless API
unless the buyer is first-party hosted (
X-Axyn-Buyer-Surface: hostedor AXYN checkout Origin). Web SDK / Mobile SDK body is kept. True hosted shop//checkout→ AXYN web +axyn.eventseven when the BFF attaches a catalog API key.
Staging smoke (ENG-489, ENG-787)
Prove on staging (never production):
- Hosted — create order via
web-axyn/axyn.events; expectcheckout_host=axyn.events,checkout_integration=axyn_webwhen BFF forwards Origin. - Embed — Web SDK partner embed; expect partner host +
web_sdk. - Headless with Origin — partner
Originor body host; expectpartner_headless/headless_api+ that host. - Headless missing host — omit Origin and
checkout_host; order create and pay still succeed; integration isheadless_api; host is the tenantwebsite_urlhost when set (neverapi.axyn.events). Logs/metrics may still showmissing_hostwhen no partner host is known. - 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.