Custom API
Headless API
Own the full buyer UI. Install **two credentials** ([Credentials](/credentials)): secret API key on the server, publishable key for buyer Auth. Your UI never sees `axyn_sk_...`. Checkout writes use a buyer JWT.
This is the highest-effort path. Prefer hosted or Web SDK embed unless you need a fully custom checkout.
Who this is for
Venue engineers building a custom storefront that talks to AXYN /v1 from a
backend (or BFF).
Architecture
Browser UI → your backend → AXYN catalog (/v1/… with x-api-key)
Browser UI → AXYN checkout (/v1/orders… with buyer JWT)
Door device → AXYN scan (x-scanner-token or staff JWT)
| Concern | Credential | Where it lives |
|---|---|---|
| Catalog reads | x-api-key + catalog:read | Your server only |
| Order create / pay | Authorization: Bearer buyer JWT | Buyer session |
| Door admit | x-scanner-token or staff JWT | Door app / staff |
Never put the tenant secret in a SPA bundle. Never send tenant_id in JSON
as authority — tenant comes from the key lookup.
Build on a draft
Before you publish, add ?include_drafts=true to a series read to also get
your own draft shows:
GET /v1/productions/{id}adds the draft shows toeventsand their types toticket_tiers.GET /v1/productions/{id}/eventsadds the draft shows. It returns shows only, never types.
It works only with your own secret key, from your server. Other organizers
never see your drafts, and neither does AXYN's hosted shop: for them the
parameter is ignored, with no error. Leave it off on your live pages. A draft
never sells: its types come back on_sale: false, and checkout refuses with
event_not_published.
Happy path (GA)
Follow Get started end to end — install two keys, mint an anonymous buyer JWT with the publishable key + Auth URL default, then catalog → order → pay. Guests never need an AXYN account. Summary:
GET /v1/events/{eventId}+GET /v1/events/{eventId}/tiers(x-api-key)- Optional:
POST /v1/orders/preview-totalfor the live total. Coupons ride an optionalcoupon_codesarray (max 5, distinct) on preview and order create; the response carriesdiscount_cents(+coupon_codesecho on preview). More than one code requires every tier in the cart to haveallow_multiple_coupons. Typed 400s:coupon_not_found(also for an expired code),coupon_inactive,coupon_not_started,coupon_exhausted,coupon_not_applicable,coupon_below_minimum_charge,coupon_duplicate,coupon_stacking_not_allowed. POST /v1/orders(anonymous buyer JWT +Idempotency-Key)POST /v1/orders/{orderId}/payments/start→ Stripe client secretPOST /v1/orders/{orderId}/verify-payment- Guest handoff (no login wall): same-session
GET /v1/me/ticketsand/or venue-branded hosted/tickets/{token}from email - Day-of: live pass on the ticket page (mint/rotate; optional device step-up)
- Door:
POST /v1/tickets/validate(x-scanner-token) orPOST /v1/tickets/scan(staff JWT)
After pay, AXYN emails a venue-branded ticket with a hosted bearer link.
You do not build /tickets/[token] for the default path — see
Ticket delivery. Confirmation is open pass, not
“save this barcode forever.”
Ticket serving is not a secret-key feature. Catalog uses x-api-key.
Guest pass + Send a pass use the public ticket-url bearer (or buyer JWT for
signed-in surfaces). Optional same-session:
POST /v1/orders/{orderId}/confirmation-bearers (buyer JWT) when you need
fresh bearers at confirmation. Details: Live pass,
Transfer, Upgrade.
Checkout refusals (sold out, not on sale, total changed, payouts not ready) are listed in Errors.
Confirm every field against $AXYN_BASE_URL/openapi.json. Do not invent
bodies.
Series and passes
A series (a run of shows) is a production. Read it with your secret key:
| Call | Returns |
|---|---|
GET /v1/productions | Your own series, each with day_ticket_type_count and pass_count |
GET /v1/productions/{id} | The series catalog: events (its shows) and ticket_tiers (day types and passes) |
GET /v1/productions/{id}/events | The series' shows only, in starts_at order |
GET /v1/events/{eventId}/tiers | One show's day types plus every pass that admits that show |
Shows list with status on_sale or sold_out. Other statuses are left
out (see Build on a draft for drafts).
Each type carries tier_scope:
occurrence: a day ticket for one show.pass: one ticket that admits several shows. It carries the seriesproduction_idandadmits, one row per admitted show (occurrence_event_id, plustitle,starts_atandvenue_namewhen known).
Series catalog types also carry on_sale. Show it as-is; do not work it out
yourself. A pass is on sale while its own sale window is open and at least one
show it admits is on sale. The show a pass is stored on does not decide this.
To sell a pass, create the order on a show the pass admits: send that show's
venue_id and venue_event_id with the pass line in POST /v1/orders. A
show the pass does not admit is refused with 400 cross_production_lines. A
cart on a series show can also carry day types from other shows of the same
series. When no show a pass admits is on sale, checkout answers with the
reason of its last show (event_not_published, sale_not_started or
sale_ended). Codes: Errors.
Names for every ticket
An organizer can turn on "Require a name for every ticket" for an event, or for a series with a per-show override. When it is on, every ticket needs a first and last name. An email per ticket is optional:
- Without an email, the ticket carries that person's name and stays with the buyer. It is delivered in the buyer's email.
- With an email, that person also gets their own pass by email (no amounts shown).
Either way the buyer holds every pass of the order: the buyer's confirmation email and confirmation screen carry a working pass for every ticket, each labelled with its attendee's name. A buyer who mistyped an email can transfer that ticket to the right person themselves.
Read the setting from the catalog:
| Where | Field |
|---|---|
GET /v1/events/{eventId} | attendee_details_mode: off or required (the effective value) |
GET /v1/events/{eventId} | attendee_details_mode_override: the show's own value, or null |
GET /v1/productions/{id} | attendee_details_mode: the series value. Pass types follow it |
GET /v1/productions/{id} events | attendee_details_mode (effective for that show) and the _override |
A ticket needs details when its own show's effective mode is required. A
pass (tier_scope: "pass") follows the series value, whatever the show it is
sold from says. On one show of a series, GET /v1/events/{eventId} carries
that value as series_attendee_details_mode (null for a standalone event). In a series cart, ask
only for the tickets that need it. Add-on lines never take an attendee.
When any ticket in the cart needs details, send attendees on
POST /v1/orders:
"attendees": [
{ "ticket_tier_id": "<uuid>", "seat_id": null, "first_name": "Ana", "last_name": "Diaz", "email": "ana@example.com" },
{ "ticket_tier_id": "<uuid>", "seat_id": null, "first_name": "Sam", "last_name": "Lee" }
]
- One entry per ticket that needs details. Entries with the same
ticket_tier_idare matched in array order. A reserved seat is matched byseat_id. first_nameandlast_name: required, 1 to 60 characters after trimming.email: optional. Leave it out (or sendnullor a blank string) for no email; a blank email is never an error. When present it must be a valid address of at most 254 characters.- The order still needs the buyer's own email (
purchaser_email). - When nothing in the order needs details, leave
attendeesout. It is ignored if sent.
Refusals are 400 with a buyer-ready message to show as-is:
error | When | message |
|---|---|---|
attendee_details_required | A ticket that needs an attendee has none, or a count is wrong | Enter a first and last name for every ticket. |
attendee_details_invalid | A value is invalid, or an entry names a type or seat not in the order | Check the name and email entered for each ticket. |
details says which ticket type, seat, entry or field to fix.
Beside the fields, you must show the buyer this notice, once:
Add an email to send someone their pass. Without one, the pass stays with you. The organizer sees these names and emails.
Use these labels so buyers see the same words everywhere: heading
Who is this ticket for?, then {ticket type name} · Ticket {n} per ticket
(the seat label instead of the number for a reserved seat), with fields
First name, Last name and Email (optional). Do not prefill the email:
blank already means the pass stays with the buyer.
The order read (GET /v1/orders/{orderId}, and the create and verify
responses) returns attendees to the buyer who owns the order; email is
null for an attendee named without one. Show the buyer every pass of the
order on your confirmation page. When some attendees have an email other
than the buyer's, add the line Also sent by email to {First Last}, {First Last}.
With the Web SDK, resolveAttendeeSlots(checkoutEvent, draft) returns the
tickets that need details, validateAttendees and serializeAttendees check
and build the array, and ATTENDEE_DETAILS_NOTE is the notice text. For a
series, spread seriesAttendeeDetailsRules(series) into the checkout event.
A transferred ticket for such an event, or a ticket the buyer named at
checkout, needs the recipient's name: the offer read
(GET /v1/ticket-transfer-claims/{token}) carries
attendee_name_required: true, and a claim without both guest_first_name
and guest_last_name is refused with 400 attendee_name_required.
Buyer JWT
Order create and pay require a buyer JWT from AXYN Auth. That JWT is a runtime token, not an installable secret.
- Install
AXYN_PUBLISHABLE_KEY(and use the Auth URL default —https://auth.axyn.eventsin production). - Mint a session with
signInAnonymously()(or magic link / OAuth). - Pass
Authorization: Bearer $BUYER_JWTon checkout routes. - Do not commit JWTs to git.
Full contract: Credentials. Details: Authentication.
Apple Pay and Google Pay
Wallets show only on a site registered on the organizer's payment account. AXYN registers the organizer's saved website (Settings › Profile, the same host recorded on your sales) on every checkout that is not on AXYN's hosted pages. You send nothing extra: the buyer JWT alone is enough.
- Only an
httpswebsite on a real host counts (nohttp,localhostor IP address). - Checkout on a different host (for example
tickets.example.comwhen the saved website isexample.com): call with the organizer's API key and the page'sOrigin(orx-axyn-checkout-origin). A page address sent without the key is never registered. - Up to 10 organizer sites per payment account.
Reserved seats (headless)
Sell reserved only when GET Event status is on_sale. Do not read
seating_ready or an attested flag on the buyer Event. An empty seat-map
means tickets are not available; chairs with none selectable is sold out.
For ticketing_layout_mode = reserved_seat:
- Load the map server-side:
GET /v1/events/{ownedEventId}/seat-map(catalog:read). - Paint House View as STAGE + named section places. Hide chair dots until the guest chooses a section. Optional list view may include chairs without coordinates. Do not invent a CAD silhouette or doors.
- Optional:
POST /v1/events/{ownedEventId}/best-available-group(section_idwhen they picked a priced place). Find N is the default door; Browse house is secondary. - Restricted: one ack before hold; repeat the same sentence at pay.
Access code opens chairs at the listed all-in. Never put the code in a
query string. Never print
hold_type. - Hold before order:
POST /v1/seats/hold(buyer JWT). Hold after ack, not at tap and not at Apple Pay. - Create the order with seat lines per OpenAPI
OrderLineInput. - Change seats before the order exists:
POST /v1/seats/releasewith the samehold_owner, then hold again. - After pay,
GET /v1/orders/{orderId}tickets include section, row, and seat labels. Missing labels on a reserved order are a defect.
For section_and_type, sell zone + quantity from tiers (section_id,
area_remaining). Do not draw chair dots.
If you want the map UI without building it, use the Web SDK seats
path (seatCatalog + CheckoutSpineRoot, or ZoneCardPicker) instead of
raw headless.
Hosted staging.axyn.events dogfoods these same /v1 contracts.
Examples use ENG-651 fixture keys only (theater-house, fan-theater,
opera-horseshoe, arena-bowl, sports-secondary, end-stage-concert).
Never branch on a partner venue name.
Partner page insights (optional)
Headless catalog GET and order create do not create Sales pageviews.
Organizer impressions / CVR for your site stay N/A until you opt in.
- In AXYN Admin → event Details, turn on Partner page insights
(default off). That unlocks
POST /v1/events/{eventId}/viewswithcheckout_integration: "headless_api". - Install the commerce pixel snippet from that same section on the ticket / checkout page only (not site-wide). Full consent and allowlist rules: Partner commerce insights & privacy.
- Gate
axyn('consent', { analytics: true })on your CMP Analytics choice, then callaxyn('view', { eventId })on the ticket page,axyn('tier_select', { eventId })when the buyer picks tickets, andaxyn('checkout_start', { eventId })when the order is created. For a series and its passes pass{ seriesId }instead on every call. Passitems: [{ tierId, quantity }]ontier_select/checkout_startso the organizer sees which ticket types people wanted (no price: AXYN prices them), andoutcomeonunavailable,payment_failedandpromo_tried. The full step list is in Partner commerce insights & privacy. Without consent or install, Sales stays N/A — never invent views from catalog reads or order create.
The pixel does not use a browser API key. Keep AXYN_API_KEY on the
server for catalog and server-side calls (Credentials).
Paid-order attribution (checkout_* on order create) still works without the
pixel. See Checkout attribution.
Required disclosure (checkout privacy notice)
Every checkout you build on the API must show AXYN's privacy notice where the buyer enters their details or card. This is the notice at the point of collection that US state privacy law (CCPA) requires, so it is not optional and not a branding choice.
Show this exact text, with Privacy as a link:
| Text | Link text | URL |
|---|---|---|
Ticketing by AXYN · Privacy | Privacy | https://axyn.events/legal/privacy |
<p>Ticketing by AXYN · <a href="https://axyn.events/legal/privacy"
target="_blank" rel="noopener noreferrer">Privacy</a></p>
- Put it under the button that submits the buyer's details
(
POST /v1/orders) or card, on every step that collects them, including cash-at-the-door and free orders. Treat it like "Powered by Stripe". - Keep it visible and readable: small type in your checkout's text color is fine. Do not hide it, collapse it behind a menu, or put it only in your site footer.
- The Web SDK renders it for you in every checkout (
PaymentForm,TicketPanel,CheckoutSpineRoot). If you use the SDK constant, importAXYN_CHECKOUT_PRIVACY_DISCLOSURE(text,linkText,url) or render<AxynPrivacyNotice />.
What not to invent
- A public list of every organizer's events.
GET /v1/eventslists only your own tenant's events. - Client-owned Stripe PaymentIntents for AXYN inventory
- Partner outbound webhooks as live (see Webhooks)
- Browser use of
x-api-key/ secret API keys (including in the commerce pixel) - Secret-key “list tickets by email” or “re-fetch raw bearer later”
- Static admit barcodes in email / PDF / wallet that bypass the live pass
- Headless pageviews from catalog
GETor order create (pixel + enable flag only)
Related
| Page | Role |
|---|---|
| Get started | Copy-paste cURL for the GA happy path |
| Credentials | Two installable keys + URL defaults |
| Authentication | Keys, scopes, JWT, scanner token |
| Errors | Envelope, status codes, rate limits |
| Testing | Sandbox checklist |
| API reference | Live OpenAPI / Scalar / Postman |
| Ticket delivery | Buy vs see-ticket; email honesty |
| Live pass | Rotating door code + step-up |
| Transfer | Send a pass / claim |
| Upgrade | Pay the all-in difference to a higher type |
| Web SDK | Lower-effort embed alternative |
| Choose integration | When to pick headless vs embed |
| Checkout attribution | Advisory host / UTM fields (never blocks sale) |
| Partner commerce insights & privacy | Optional headless pageview pixel + disclosure |