SeatBuilderSeatBuilder Docs
Seats

Hold seats

Places a hold on the requested seat label for the calling workspace. 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.

POST/api/v1/events/{eventKey}/seats/hold

Path Parameters

eventKeystring

Request Body

objectLabelstring

The seat label as defined on the chart (e.g. "A-12" for row A seat 12, or "VIP-G3" for a section seat). For GA areas, use the area key with objectType: "generalAdmission".

Length1 <= length
holdTokenstring

Client-generated token (≥ 8 chars; recommended: random UUID). Pass the same token to /book to confirm or /release to cancel the hold. The SDK generates one automatically per chart session.

Length8 <= length
ttlSeconds?integer

Hold expiry in seconds. Defaults to 900 (15 minutes) when omitted. Holds auto-expire and emit a seat.hold_expired webhook if a subscription exists.

Range0 < value
extraData?object

Arbitrary JSON metadata attached to this status change (e.g. { orderId: "ord_98a2", buyerName: "Alex Doe" }). Surfaces in subsequent webhook payloads and the event status response.

Empty Object

objectType?string

Optional seat-vs-GA discriminator. Provide "generalAdmission" for GA holds; omit for individual seat holds.

categoryKey?string

Optional category (pricing zone) key — narrows the hold to that category if present. Useful for GA areas with multiple price points.

quantity?integer

Number of GA tickets to hold in a single operation. Only valid when objectType is "generalAdmission". Defaults to 1 when omitted. Must not exceed the GA area capacity minus currently-held tickets for this area.

Range1 <= value

Response Body

curl -X POST "http://localhost:3000/api/v1/events/string/seats/hold" \  -H "Content-Type: application/json" \  -d '{    "objectLabel": "string",    "holdToken": "stringst"  }'

{
  "chartKey": "chart_8a2b1c",
  "eventKey": "evt_q3-2026-jazz-night",
  "objectLabel": "A-12",
  "status": "held",
  "holdToken": "7f6c3a91-b1ef-4d0a-9c84-3f12a8e0b5d2",
  "holdExpiresAt": "2026-10-02T18:55: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"
    ]
  }
}
{
  "statusCode": 0,
  "message": "string",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Seats

hold, book, and release individual seats on an event.

Book held seats POST

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.