Events

An event is an immutable seating snapshot plus live inventory. Create it from a published chart, sell against its event key, and update the snapshot deliberately when the source chart changes.

Create an event

curl -sX POST "https://api.seatlayer.io/v1/events" \
  -H "authorization: Bearer $SEATLAYER_SECRET_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: event_order_8271" \
  -d '{
    "chartId": "chart_abc",
    "name": "Opening Night",
    "slug": "opening-night",
    "startsAt": 1767204000000,
    "venue": "Main Hall",
    "externalRef": "show_8271",
    "currency": "GBP"
  }'

The chart must be published and belong to an active workspace. A live event requires a positive credit balance; test events do not consume credits.

A successful response is 201 {"meta": EventMeta}. Event creation supports Idempotency-Key; retry the same logical create with the same key and body.

List and retrieve

Use workspaceId to select an active workspace and externalRef to find the event belonging to a host record:

curl -s \
  "https://api.seatlayer.io/v1/events?workspaceId=ws_main&externalRef=show_8271" \
  -H "authorization: Bearer $SEATLAYER_SECRET_KEY"

The response includes events[], with cached metadata, mode, sold, and live counts where available.

The detail response contains:

{
  "meta": {
    "key": "opening-night",
    "name": "Opening Night",
    "chartId": "chart_abc",
    "status": "active",
    "seatTotal": 1200,
    "mode": "live",
    "workspaceId": "ws_main",
    "externalRef": "show_8271",
    "currency": "GBP",
    "sold": 412,
    "inventoryModelVersion": 2
  },
  "counts": {
    "free": 760,
    "held": 8,
    "booked": 412,
    "blocked": 20
  },
  "holdTtlMs": null,
  "chartUpdate": {
    "behind": false,
    "canAutoUpdate": false
  }
}

holdTtlMs: null means the default 15-minute hold window applies.

Update metadata and section state

Send only the fields to change:

{
  "name": "Opening Night — Rescheduled",
  "startsAt": 1767290400000,
  "venue": "Main Hall",
  "externalRef": "show_8271",
  "currency": "GBP",
  "sectionStates": {
    "sec-balcony": "hidden",
    "sec-stalls": "open"
  }
}

startsAt, venue, externalRef, and currency can be cleared with null. Section and zone states are open, closed, or hidden; unknown ids return 422. An empty patch returns 400 nothing_to_update.

For timed and demand-triggered section release, use inventory and availability.

Update an event to the latest chart

Publishing a changed chart reports whether existing events refreshed automatically or need a manual update. Pristine events can refresh without inventory risk. Events with live state require the explicit route:

curl -sX POST \
  "https://api.seatlayer.io/v1/events/opening-night/update-chart" \
  -H "authorization: Bearer $SEATLAYER_SECRET_KEY"

If a booked or held label would disappear, the update fails atomically:

{
  "error": "seats_would_vanish",
  "code": "seats_would_vanish",
  "missingLabels": ["A-12"],
  "message": "The update would remove booked or held seats."
}

Archived and deleted events are not mutable. Never work around a conflict by recreating the event; reconcile the affected chart labels and retry.

Lifecycle

Use close for a reversible pause. Archive after the event ends; SeatLayer writes a durable inventory snapshot and keeps the live store for reports. Delete is a soft delete rather than immediate physical erasure.

Supported application transitions are:

active -> closed -> active
active or closed -> archived
active, closed, or archived -> deleted

Errors to handle

Verification

• Event creation has a stable idempotency key.
• Host records store the returned event key and workspace id.
• Test and live resources use matching secret-key modes.
• The event’s currency, name, start time, and external reference are checked.
• Chart updates are tested with booked and held inventory.
• Close, archive, and delete are explicit operator actions.

Continue to inventory, booking, and reports.