Book held seats
Confirms one or more previously-held seats as booked in a single atomic, all-or-nothing batch. Pass every seat label in `objectLabels[]`; all must currently be held under the same `holdToken` returned from `/hold`. If any one seat is no longer held by that token, the whole request fails with `409` and nothing is booked. Booked seats remain in `booked` status until explicitly released via `/release`. Emits one `seat.booked` webhook per booked seat if a subscription exists.
/api/v1/events/{eventKey}/seats/bookPath Parameters
Seat labels to book in one atomic request. Single seat = array of one. All must be held by the supplied holdToken or the whole request fails. A general-admission area is booked under its GA hold (pass the holdToken returned from the GA /hold), NOT as an individual seat — a bare GA-area label with no matching GA hold is rejected 400.
1 <= items <= 200The holdToken returned from the preceding /hold call(s). All listed labels must be held under this token.
1 <= lengthArbitrary JSON metadata merged onto EVERY booked seat (e.g. one { orderId } for the whole order).
Empty Object
Response Body
curl -X POST "https://seatbuilder.org/api/v1/events/string/seats/book" \ -H "Content-Type: application/json" \ -d '{ "objectLabels": [ "A-12", "A-13" ], "holdToken": "7f6c3a91-b1ef-4d0a-9c84-3f12a8e0b5d2", "extraData": { "orderId": "ord_98a2" } }'{
"booked": [
{
"chartKey": "chart_8a2b1c",
"eventKey": "evt_q3-2026-jazz-night",
"objectLabel": "A-12",
"status": "booked",
"bookedAt": "2026-10-02T18:46:00.000Z",
"extraData": {
"orderId": "ord_98a2"
}
},
{
"chartKey": "chart_8a2b1c",
"eventKey": "evt_q3-2026-jazz-night",
"objectLabel": "A-13",
"status": "booked",
"bookedAt": "2026-10-02T18:46:00.000Z",
"extraData": {
"orderId": "ord_98a2"
}
}
]
}{
"statusCode": 0,
"message": "string",
"errors": {
"property1": [
"string"
],
"property2": [
"string"
]
}
}{
"statusCode": 0,
"message": "string",
"errors": {
"property1": [
"string"
],
"property2": [
"string"
]
}
}{
"statusCode": 0,
"message": "string",
"errors": {
"property1": [
"string"
],
"property2": [
"string"
]
}
}{
"statusCode": 0,
"message": "string",
"errors": {
"property1": [
"string"
],
"property2": [
"string"
]
}
}{
"error": "One or more seats are no longer held by this token",
"failed": [
{
"objectLabel": "A-13",
"reason": "not_held_by_token"
}
]
}{
"statusCode": 0,
"message": "string",
"errors": {
"property1": [
"string"
],
"property2": [
"string"
]
}
}Hold seats POST
Places a hold on the requested seat(s) for the calling workspace. Pass `objectLabels[]` — the single canonical request shape — to hold N individual seats atomically under one `holdToken` (all-or-nothing: if any seat cannot be held the whole request fails `409` and nothing is held). A single seat is a one-element array. GA areas ride on a single-element array: pass `objectLabels: ["GA-LAWN"]` together with `objectType: "generalAdmission"`, `quantity`, and (optionally) `categoryKey`; those GA fields are only valid on a one-element array. The hold lasts `ttlSeconds` (default 900). Pass the returned `holdToken` to `/book` to confirm purchase or `/release` to cancel. Holds expire automatically; subscribers to `seat.hold_expired` receive a webhook on expiry. Atomic via Redis SET NX EX — concurrent hold attempts on the same seat never double-book. The response is always the array shape ({ chartKey, eventKey, holdToken, holdExpiresAt, objects: [...] }), whether one seat or many.
Release seats POST
Returns one or more seats to `free` status in a single atomic, all-or-nothing batch. Works on both held and booked seats. Use this when a purchase is cancelled, a hold needs to be voluntarily released before TTL expiry, or a booking is refunded. If any one requested label is not currently held or booked, the whole request fails with `409` and nothing is released. Emits one `seat.released` webhook per released seat if a subscription exists.