Skip to content

Custom API

Waitlist

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

Waitlist

Sold-out Get tickets stays Sold out. Guests pay only if they claim. TicketPanel does not mount Join yet, and Join never appears without that API answering healthy.

Who this is for

Venue engineers embedding TicketPanel or calling Partner /v1. Organizers who want waitlist on an event. This page is honesty first, not a full how-to.

Status

Early. The published API spec now carries a sold-out waitlist: a public join, a proof-gated status lookup (reference plus email), and a claim link that starts pay. Organizer staff can list entries, make an offer that soft-holds inventory, and remove an entry. See the waitlist tag in the Full API list. Do not invent paths, HMAC headers, or a second pass.

What is not there yet:

  • TicketPanel and hosted pages do not mount a Join CTA
  • Offers are made by organizer staff one at a time; nothing releases them automatically when inventory frees up
  • AXYN does not email the guest at join or at offer. The claim link comes back only to the staff caller that made the offer

The organizer opt-in gates join. Event.waitlist_join_mode is off, sold_out, or always on GET|POST|PATCH /v1/events. off is the default and refuses every join. sold_out accepts only once no sellable units remain; always accepts while the sales window is open. Organizers set it on event Setup under "Make it sell". Buyer EventDetail does not carry it, so a buyer page cannot tell from the catalog whether join is open.

Until Join is mounted, poll catalog and show Sold out. Hosted and embed already drop Find N type: waitlist.

Auth

Tenant API keys authorize only that tenant. Never send tenant_id from the browser as authority. Examples use opaque placeholders ($EVENT_ID, $TENANT_ID), not other-tenant ids.

What waitlist is

Join is free. AXYN does not charge a card and holds no inventory at join. If a ticket becomes available, the guest gets an offer, then a claim window, then pay. The offer soft-holds those tickets only for that window. A missed claim does not bill them: the hold goes back on sale and the guest is waiting again.

A claim link is live only while its hold can still be paid. Once the hold expired or was cancelled, the link says expired. Once the order is paid, the link is spent and reads as not found. Opening the link never starts a charge; only the explicit pay step does.

Emails about a different ticket type require opt-in and name that type. Do not email GA waiters about VIP unless they opted in for that named type.

Upgrade is not waitlist. Holders who already have a pass pay a delta on the same Live Pass URL. That is not a second pass and not a waitlist claim. See Upgrade.

This is not a restaurant waitlist. SEEAT walk-in queues are a different product. Do not reuse hospitality waitlist flags or views.

Find N is not Join

POST /v1/events/$EVENT_ID/best-available-group may still return alternatives[].type: waitlist when the searchable pool has fewer than N seats (or no sections). That enum is a miss, not a signup API. TicketPanel and Best available drop that row and never show Join. An empty house is Sold out. Leftover chairs that cannot sit N are not Sold out.

Do not paint Join from that alternative. Do not POST a waitlist body to that route.

TicketPanel / Get tickets

Join is unmounted today, even though the join API exists. When TicketPanel mounts it, Join will show only when all of these are true:

  1. The organizer opted in (waitlist_join_mode is not off)
  2. The type is sold out or short
  3. The waitlist API answers healthy

Until then, Join stays hidden even if you cache a sold-out page. Revalidation must not revive Join from a stale opt-in or from Find N type: waitlist. When the API is unhealthy, hide Join.

Common mistakes

  • Showing Join because Find N returned type: waitlist
  • Showing Join because waitlist_join_mode is sold_out or always
  • Charging at join
  • Emailing a different type without opt-in, or without naming that type
  • Teaching waitlist claim as an upgrade or a second Live Pass
  • Copying SEEAT restaurant waitlist
  • Documenting platform-ops waitlist recipes (never sold)
  • Using another tenant's event id in examples

Next