Skip to content

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)
ConcernCredentialWhere it lives
Catalog readsx-api-key + catalog:readYour server only
Order create / payAuthorization: Bearer buyer JWTBuyer session
Door admitx-scanner-token or staff JWTDoor 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 to events and their types to ticket_tiers.
  • GET /v1/productions/{id}/events adds 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:

  1. GET /v1/events/{eventId} + GET /v1/events/{eventId}/tiers (x-api-key)
  2. Optional: POST /v1/orders/preview-total for the live total. Coupons ride an optional coupon_codes array (max 5, distinct) on preview and order create; the response carries discount_cents (+ coupon_codes echo on preview). More than one code requires every tier in the cart to have allow_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.
  3. POST /v1/orders (anonymous buyer JWT + Idempotency-Key)
  4. POST /v1/orders/{orderId}/payments/start → Stripe client secret
  5. POST /v1/orders/{orderId}/verify-payment
  6. Guest handoff (no login wall): same-session GET /v1/me/tickets and/or venue-branded hosted /tickets/{token} from email
  7. Day-of: live pass on the ticket page (mint/rotate; optional device step-up)
  8. Door: POST /v1/tickets/validate (x-scanner-token) or POST /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:

CallReturns
GET /v1/productionsYour 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}/eventsThe series' shows only, in starts_at order
GET /v1/events/{eventId}/tiersOne 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 series production_id and admits, one row per admitted show (occurrence_event_id, plus title, starts_at and venue_name when 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:

WhereField
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} eventsattendee_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_id are matched in array order. A reserved seat is matched by seat_id.
  • first_name and last_name: required, 1 to 60 characters after trimming.
  • email: optional. Leave it out (or send null or 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 attendees out. It is ignored if sent.

Refusals are 400 with a buyer-ready message to show as-is:

errorWhenmessage
attendee_details_requiredA ticket that needs an attendee has none, or a count is wrongEnter a first and last name for every ticket.
attendee_details_invalidA value is invalid, or an entry names a type or seat not in the orderCheck 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.

  1. Install AXYN_PUBLISHABLE_KEY (and use the Auth URL default — https://auth.axyn.events in production).
  2. Mint a session with signInAnonymously() (or magic link / OAuth).
  3. Pass Authorization: Bearer $BUYER_JWT on checkout routes.
  4. 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 https website on a real host counts (no http, localhost or IP address).
  • Checkout on a different host (for example tickets.example.com when the saved website is example.com): call with the organizer's API key and the page's Origin (or x-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:

  1. Load the map server-side: GET /v1/events/{ownedEventId}/seat-map (catalog:read).
  2. 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.
  3. Optional: POST /v1/events/{ownedEventId}/best-available-group (section_id when they picked a priced place). Find N is the default door; Browse house is secondary.
  4. 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.
  5. Hold before order: POST /v1/seats/hold (buyer JWT). Hold after ack, not at tap and not at Apple Pay.
  6. Create the order with seat lines per OpenAPI OrderLineInput.
  7. Change seats before the order exists: POST /v1/seats/release with the same hold_owner, then hold again.
  8. 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.

  1. In AXYN Admin → event Details, turn on Partner page insights (default off). That unlocks POST /v1/events/{eventId}/views with checkout_integration: "headless_api".
  2. 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.
  3. Gate axyn('consent', { analytics: true }) on your CMP Analytics choice, then call axyn('view', { eventId }) on the ticket page, axyn('tier_select', { eventId }) when the buyer picks tickets, and axyn('checkout_start', { eventId }) when the order is created. For a series and its passes pass { seriesId } instead on every call. Pass items: [{ tierId, quantity }] on tier_select / checkout_start so the organizer sees which ticket types people wanted (no price: AXYN prices them), and outcome on unavailable, payment_failed and promo_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:

TextLink textURL
Ticketing by AXYN · PrivacyPrivacyhttps://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, import AXYN_CHECKOUT_PRIVACY_DISCLOSURE (text, linkText, url) or render <AxynPrivacyNotice />.

What not to invent

  • A public list of every organizer's events. GET /v1/events lists 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 GET or order create (pixel + enable flag only)
PageRole
Get startedCopy-paste cURL for the GA happy path
CredentialsTwo installable keys + URL defaults
AuthenticationKeys, scopes, JWT, scanner token
ErrorsEnvelope, status codes, rate limits
TestingSandbox checklist
API referenceLive OpenAPI / Scalar / Postman
Ticket deliveryBuy vs see-ticket; email honesty
Live passRotating door code + step-up
TransferSend a pass / claim
UpgradePay the all-in difference to a higher type
Web SDKLower-effort embed alternative
Choose integrationWhen to pick headless vs embed
Checkout attributionAdvisory host / UTM fields (never blocks sale)
Partner commerce insights & privacyOptional headless pageview pixel + disclosure

Next