Core concepts

Before you wire SeatBuilder into a checkout, it helps to hold the same mental model the platform is built around. Everything below is a concept you will meet again in the hold and book lifecycle and the webhooks guides — this page is the map.

Charts and events

SeatBuilder separates the reusable venue layout from the individual occasions that sell it.

• A chart is the venue layout you build in the editor: sections, rows, seats, tables, general-admission areas, and pricing categories. A chart is versioned — you edit a draftVersion and promote it to a publishedVersion when it is ready to sell.
• An event is a single occasion (one performance, one match, one showing) that references a published chart. Each event has its own independent seat availability, so the same chart can back a hundred events without their inventories colliding.

An event is addressed by its eventKey; a chart by its chartKey. When you read an event back you also see the chartPublishedVersion it is rendering — re-publishing a chart propagates the new layout to every event that references it on next read. See Versioning for the exact snapshot policy.

The seat lifecycle

Every seat in an event moves through a small, well-defined set of statuses:

The normal flow is:

free → held → booked

A hold is transient: if the buyer walks away, the hold expires at holdExpiresAt and the seat returns to free on its own — the platform emits a seat.hold_expired event when that auto-expiry fires. You can also give a held or booked seat back to inventory explicitly with the release endpoint, which returns it to free:

held  → (release)  → free
booked → (release) → free

Hold-token ownership

A hold token is the secret that proves who owns a hold. When a buyer selects a seat in the browser, the SDK takes a hold and hands your code a holdToken. That token — and only that token — may extend the hold, book the seat, or release it. Treat it like a short-lived bearer credential: persist it alongside the buyer's cart, and pass it on every follow-up call.

The hold token is deliberately absent from webhook payloads (see Webhooks) — the event tells you a seat changed state, not who holds it.

The SDK and the REST API

SeatBuilder has two surfaces, and a typical integration uses both:

• The browser SDK renders the interactive seat map. You load it from the /sdk/ route and call window.SeatBuilder.render(config) (or import SeatBuilder from '@seatbuilder/sdk' once the npm package ships). The SDK authenticates with a public key (pk_live_xxx) that is safe to expose in the browser, and it takes the initial browse-hold when a buyer clicks a seat.
• The REST API is your server-side surface. It authenticates with a secret key (sk_live_xxx) via the X-Api-Key header and drives the authoritative hold → book → release flow. The secret key must never reach the browser — see Server-side integration.

Put together: the SDK renders the map and captures a holdToken in the browser; your backend mirrors and confirms that hold against the REST API with the secret key; webhooks tell your backend when seat state changes out from under you.

Where to go next

• Hold and book lifecycle — the full hold → book → release flow with verbatim request and response JSON for every endpoint.
• Webhooks — the event types, the envelope, and signature verification.
• Server-side integration — the secret-key backend flow and how to keep the secret key off the client.