Checkout flow

Browse events and tickets

Use GET /events to list your host's public events. Each item is an EventSummary, with the fields needed for an event listing such as its name, poster, date, location, status, and cheapest price.

For an event page, use GET /events/{slug}. It returns the full Event, including headliners: the public guests and performers featured on the event page. A headliner has a name, optional role and image, an isMainArtist flag, and an optional Spotify or Deezer artist profile.

Load supporting images from GET /events/{slug}/gallery. Its items are returned in stable creation order, and each includes an imageURL plus optional altText. Then use GET /events/{slug}/tickets to show the purchasable ticket types. Each ticket includes live availability (quantityLeft), pricing, and a status such as AVAILABLE or SOLD_OUT.

Reserve tickets

When the attendee picks tickets, call POST /events/{slug}/reservations. This prices the cart and holds the stock for the checkout window, and returns:

• reservationToken: identifies the attendee's cart. Echo it as the X-Device-ID header on the order and release calls.
• quoteReference: an opaque handle to the priced, server-held quote.
• total, totalFees, items: the priced cart, in the smallest currency unit.
• promoCode, discount: the event-scoped promo code and discount, when one was applied.
• clientExpiresAt: drive a countdown timer on your checkout page.

Calling it again with the same X-Device-ID refreshes/extends the same reservation instead of holding fresh stock. See Reservations for the details.

To apply a promo code, include promoCode in the reservation body. Codes must belong to the event in {slug}; global promo codes are not supported. The reservation response is the source of truth for the applied discount. See Promo codes.

Render your checkout page

Collect the attendee's details (email, first name, last name) on your own checkout UI while the countdown runs. Tickets are issued to the email you submit.

Create the order

Call POST /events/{slug}/orders with the quoteReference in the body and the reservationToken echoed as X-Device-ID:

• Free (zero-total) orders are fulfilled immediately and return status: "confirmed" with the order reference.
• Paid orders return status: "pending_payment" and a checkoutUrl. This is the payment link the attendee uses to pay. After payment, the attendee is sent to your callbackUrl with a reference query parameter.

A duplicate order for the same reservation returns 409.