How the Booking API works
- Last verified
- Last verified Sep 23, 2026
The Booking API lets your own website or app sell what a KORONA Event shop sells: tickets for dated events and time slots, admissions, products and vouchers. This article explains the model behind the API. The Booking API quickstart walks through a complete purchase.
The API is a GraphQL endpoint at /api/graphql/booking/v1 on your KORONA Event API host. Every request identifies the shop with the X-Tenant-Domain header, set to the shop's domain. Send Accept-Language to receive translated names, legal texts and payment pages in that language.
Integration levels
Choose how much of the purchase your application handles.
| Level | Your application handles | KORONA Event handles |
|---|---|---|
| Hosted payment (recommended) | Offer display, date and time selection, cart, codes, customer data, legal consent and checkout | Payment method selection, card and wallet payments, 3-D Secure, payment recovery and the confirmation page |
| Fully headless | Everything above plus the payment itself | Payment processing through the connected payment provider |
With hosted payment, your application completes checkout and then sends the customer to the payment link that KORONA Event returns. The customer pays on the shop's hosted payment page, which supports every payment method configured for the shop. The Booking API also exposes paymentIntentCreate for headless payment-provider integrations. This article and the guides describe hosted payment; see the generated API reference and your provider's integration requirements for headless payment.
The purchase model
A purchase moves through four records.
| Record | API type | What it is |
|---|---|---|
| Offer | Event, EventTemplate, Admission, Product, VoucherConfiguration | Something the shop sells. offers lists them and offer reads one. |
| Cart | Request | The customer's order while it is being built and after checkout. Each line is a RequestItem. |
| Invoice | Invoice | Created at checkout when something is payable. Payment attempts belong to the invoice. |
| Tickets | URL on the cart | shareablePublicTicketsUrl(format:) links to the customer's tickets once they are available. |
A cart line always points to one offer and contains one or more pricings. A pricing is a quantity at one price: for events and time slots the price comes from a price rule (PRICE_RULE), for products from the product (PRODUCT), and for vouchers from the voucher configuration (VOUCHER_CONFIGURATION). The server always calculates prices; the Booking API does not accept prices from the client.
Tokens
The Booking API has no API key. Access to a cart or invoice comes from its token, and customer accounts use their own token.
| Token | Where you get it | Where you send it |
|---|---|---|
| Cart token | request.accessToken from the first cart mutation | The id of request and cart mutations, or requestId when adding or changing cart lines |
| Invoice token | invoice.accessToken from requestPaymentInitiate | The id of invoice |
| Customer login token | contact.authToken from contactLogin | Authorization: Bearer <token>, only for customer-account operations |
Treat cart and invoice tokens like passwords: anyone with the token can read and change that cart or invoice. Keep them in your session storage rather than in URLs you share. Cart and invoice tokens are not interchangeable.
Checkout states
request.checkoutPolicy tells you how the cart completes. Read it before checkout.
targetState | What checkout does | Booking API support |
|---|---|---|
BOOKED | Books the cart and creates the invoice to pay | requestPaymentInitiate |
RESERVED | Reserves the cart until a deadline without payment | Not yet available. Link to the offer in the hosted shop instead. |
REQUESTED | Sends a booking inquiry for staff to confirm | Not yet available. Link to the offer in the hosted shop instead. |
When checkoutPolicy.compatible is false, the cart mixes offers that cannot be checked out together. checkoutPolicy.conflicts lists the cart lines involved; ask the customer to remove them or check them out separately.
After checkout, request.state is BOOKED and invoice.paymentState moves from REQUIRES_PAYMENT to PAID when payment succeeds.
Checkout hold
While a customer shops, the cart holds its places for a limited time. request.checkoutHold.expiresAt and secondsRemaining tell you how long. When the hold ends, KORONA Event cancels the unpaid cart and releases its places, and further changes to the cart fail with a checkoutHold error. Show a countdown and start a new cart when the hold has ended.
Errors
A response can succeed at the HTTP level and still fail. Check the top-level GraphQL errors first, then the mutation's own errors list. Mutation errors have a machine-readable message, the input key it concerns, and a translated messageTranslated you can show to the customer. Get API access explains the error layers in detail.
Do not repeat a checkout or payment write automatically when a response is missing. Read the cart or invoice first to see whether the write succeeded.
