Holds & booking

Every seat is free, held or booked. Holds are temporary and owned by a hold token; bookings are permanent until you release them.

Holding

• POST /v1/events/:key/hold with { seatIds, holdToken, ttlSeconds? } and the public key.
• Up to 200 seat ids per request, here and when booking.
• All seats or none: if any seat is taken you get 409 SEATS_UNAVAILABLE listing it, and nothing is held.
• Holding again with the same token extends the hold. Default 600 s; allowed 60–1800 s.
• Unknown or permanently blocked seat ids return 400 UNKNOWN_SEATS (hold, book and release-booking).

Booking

From your server, with the secret key:

POST /v1/events/:key/book
Authorization: Bearer sk_...
{ "seatIds": ["row-1-seat-4"], "holdToken": "...", "orderId": "order-1042" }

201 { "seatIds": ["row-1-seat-4"], "orderId": "order-1042" }
409 { "statusCode": 409, "error": "Conflict", "message": "SEATS_UNAVAILABLE", "seatIds": [...] }
400 { "statusCode": 400, "error": "Bad Request", "message": "UNKNOWN_SEATS", "seatIds": [...] }

A seat can be booked only once; two simultaneous bookings for the same seat cannot both succeed. Seats that are free, or held by the given holdToken, can be booked. An expired hold is fine as long as nobody else took the seat. A seat held by another token, or already booked, is refused with 409, and nothing is booked. orderId is optional.

Releasing

• POST /v1/events/:key/release (public key) frees seats held by a token. Omit seatIds to release everything the token holds; ids it does not hold are ignored.
• POST /v1/events/:key/release-booking (secret key) un-books seats, for refunds.

Live updates

Every hold, release and booking shows up on all open maps for that event straight away. The embed handles this for you.