---
title: "Events"
description: "Create events from published charts, read live counts, update metadata and chart snapshots, and manage the event lifecycle."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.seatlayer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

An event is an event-owned seating and pricing snapshot plus live inventory.
Create it from a published chart, address that inventory through its event key,
and update the map deliberately when the source chart changes. Dashboard users
can edit an event's normal prices without changing sibling events on the same
chart; existing hold and booking prices remain locked.

For a Platform/API integration, this is an infrastructure Event: it does not
imply a SeatLayer catalogue entry, Hosted Event Page, Organizer Website,
managed checkout, commerce Order, or ticket. Keep those in your platform unless
the organizer deliberately uses the separate Hosted Ticketing product.

Every Event is created from a published reserved-seat Chart. GA areas may exist
inside that Chart, but a pure-GA event without a seating chart is not a supported
target. Platform/SDK versus Managed commerce ownership is also fixed when the
Event is created; reuse the Chart and create a new Event to change products.

> **Chart and event are different resources**
>
> Map refresh protects booked and held labels. Chart price changes are separate:
> linked events retain their prices until an organizer explicitly applies the
> new defaults in the dashboard.

## Create an event

**POST /v1/events**. Authentication: Secret key or dashboard session

```bash title="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",
    "region": "western-europe",
    "externalRef": "show_8271",
    "currency": "GBP"
  }'
```

The chart must be published and belong to an active
[workspace](/platform/workspaces/). A live event
requires a positive credit balance; test events do not consume credits.

| Field | Type | Required | Behavior |
|---|---|---|---|
| `chartId` | `string` | Yes | Published source chart |
| `name` | `string` | No | Defaults to chart name |
| `slug` | `string` | No | 3–64 lowercase letters, digits, `_`, or `-`; becomes the event key. Slugs are unique per workspace: when another customer already uses one, a numeric suffix is appended (`opening-night-2`), so always read the key from `meta.key` |
| `startsAt` | `number` | No | Epoch milliseconds |
| `venue` | `string` | No | Venue label |
| `mode` | `"live" \| "test"` | No | Session calls only; a secret key's mode wins |
| `externalRef` | `string` | No | Host identifier, at most 128 characters |
| `currency` | `string \| null` | No | Three-letter event override; otherwise org currency |
| `description` | `string \| null` | No | Event description used by share and hosted surfaces |
| `endsAt` | `number \| null` | No | End time in epoch milliseconds; cannot precede `startsAt`. It is the show's end and never stops sales |
| `salesCloseAt` | `number \| string \| null` | No | When online sales close on their own: epoch ms or an ISO time with an offset (`2026-10-23T19:30:00+01:00`). Must be in the future. Left out, sales stay open until you close them |
| `autoEndAt` | `number \| string \| null` | No | When the event ends on its own, as [`POST /:key/end`](#close-reopen-and-end). Must be in the future and not before `salesCloseAt` |
| `timezone` | `string \| null` | No | IANA time zone such as `Asia/Kolkata`. Send it: times are read in this zone. Left out, the event takes the usual zone of your events (see below); `null` keeps it unset |
| `region` | `string` | No | One of the 11 [Event regions](/server-api/event-regions/); otherwise the workspace default |
| `locale` | `string \| null` | No | BCP-47 language tag such as `hi-IN` |
| `posterAssetId` | `string \| null` | No | Previously staged dashboard poster asset |
| `async` | `true` | No | Dashboard sessions only. Answers as soon as the event row is durable and copies the chart pin and inventory behind the response; `meta.provisioning` is `true` until they land (typically ~2 s). Ignored for secret-key callers, whose events are always provisioned in the request |

A successful response is `201 {"meta": EventMeta}`. When the request
sent no `timezone`, the event takes the zone your events usually use: the most
common zone among the 200 newest events on the same chart, then in the
workspace, then in the organization (a tie goes to the zone used most
recently). The response then also carries
`timezoneDefault: {"applied": "Europe/Berlin", "from": "chart"}` (`from` is
`chart`, `workspace` or `organization`), and `meta.timezone` holds the same
zone. A request that sends `timezone`, even as `null`, keeps its own value,
and existing events never change. With no zoned event to learn from, the
zone stays unset. Store `meta.key` beside
your platform's own event ID; it is the inventory key used by the buyer SDK and
server booking calls. A secret-key-created event starts with Platform checkout
authority and live inventory immediately; it does not require event-page
details or SeatLayer ticket releases. Event creation supports
`Idempotency-Key`; retry the same logical create with the same key and body.

While `meta.provisioning` is `true` (dashboard `async` creates only), every
route that reads the event's chart pin or inventory (buyer bootstrap, chart,
availability, holds, and the organizer chart, pricing and report reads)
answers `503 event_provisioning` with `Retry-After: 2` rather than a `404`.
Poll `GET /v1/events/{key}` until the flag is absent; `seatTotal` is the
chart's seat count until then. A secret-key create never returns the flag.

Choose `region` when creating the event: an event's live inventory is placed
in its region when the event is first used, and an existing event cannot be
moved by changing later requests. Pick the broad region nearest the **event venue**, not the
developer, API server, or organizer creating it.

For Rotterdam use `western-europe`; for India use `asia-pacific`. Omit `region`
to inherit the chart workspace's default. See the [11-region reference and
resolution rules](/server-api/event-regions/). Placement is a best-effort
latency preference, not a legal data-residency guarantee.

Ticket releases are optional. A Platform integration can keep its own on-sale
windows and pricing policy while using SeatLayer inventory, or manage
event-scoped releases through the API described below.

> **Choose Public or scoped browser access**
>
> Secret-key-created Platform events are embed-only. For ordinary Public sale,
> mount the Buyer SDK with the event key plus its account's publishable
> `pk_test_…` or `pk_live_…` key. SeatLayer validates the exact registered
> browser origin and returns one Public-only in-memory session together with the
> chart and compact inventory status. Login, presale, partner, and channel
> inventory still require an exact-origin
> [buyer access session](/server-api/buyer-access-sessions) from your backend.
> An explicit buyer token/provider takes precedence over `publicKey`; an event
> key by itself still receives `404`. Secret-key hold and booking calls are
> unchanged.

## List and retrieve

**GET /v1/events**. Authentication: Secret key or dashboard session

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

```bash
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. A secret key receives only events matching its own
`live` or `test` mode. A dashboard session receives both modes for the selected
workspace. Environment tags do not filter event lists or event access.

Mode filtering happens before `externalRef`, paging, and counts are returned.
When no event in the key's mode matches the other filters, the list returns
`200 {"events":[]}`; list calls do not return `mode_mismatch`. Direct access to
a same-organization event in the opposite mode remains an explicit
`403 {"error":"mode_mismatch"}`. Unknown and other-organization event keys
remain non-disclosing `404` responses.

### Paging

The list is paginated. A response carries at most `limit` events (default 100,
maximum 200) plus a `nextCursor` when more remain; the absence of `nextCursor`
means you have reached the end.

```bash
curl -s "https://api.seatlayer.io/v1/events?limit=50" \
  -H "authorization: Bearer $SEATLAYER_SECRET_KEY"
# → { "events": [ … ], "nextCursor": "MTc1NDA2…" }

curl -s "https://api.seatlayer.io/v1/events?limit=50&cursor=MTc1NDA2…" \
  -H "authorization: Bearer $SEATLAYER_SECRET_KEY"
```

Cursors are opaque: pass back exactly what you were given and do not construct
one. A cursor we cannot read restarts the list from the beginning rather than
erroring, so a stale bookmark degrades instead of breaking. An oversized `limit`
clamps to the maximum rather than being rejected.

> **Turn off counts when walking the whole catalogue**
>
> Live `counts` are computed per event, which costs one internal round-trip
> each. Pass `counts=0` when you are paging every event and only need metadata:
>
> ```bash
  curl -s "https://api.seatlayer.io/v1/events?limit=200&counts=0" \
-H "authorization: Bearer $SEATLAYER_SECRET_KEY"
```
>
> The [server SDKs](/server-sdk/install/) do this for you: their `listAll`
> helpers page transparently and drop counts by default.

`GET /v1/charts` pages the same way, with `limit` and `cursor`.

**GET /v1/events/:key**. Authentication: Secret key or dashboard session

The detail response contains:

```json
{
  "meta": {
    "key": "opening-night",
    "name": "Opening Night",
    "chartId": "chart_abc",
    "status": "active",
    "seatTotal": 1200,
    "mode": "live",
    "workspaceId": "ws_main",
    "externalRef": "show_8271",
    "currency": "GBP",
    "region": "western-europe",
    "sold": 412,
    "inventoryModelVersion": 2
  },
  "counts": {
    "free": 760,
    "held": 8,
    "booked": 412,
    "blocked": 20
  },
  "holdTtlMs": null,
  "chartUpdate": {
    "behind": false,
    "canAutoUpdate": false,
    "chartVersionAt": "2026-09-28T14:05:00.000Z"
  }
}
```

`counts.free` counts seats whose status is free, so it includes free seats in a not-for-sale category. Buyers can't hold those seats.
`holdTtlMs: null` means the default 15-minute hold window applies.
`chartUpdate.chartVersionAt` is when the chart version this event runs on was saved, or `null` when that isn't known.

## Update metadata and section state

**PATCH /v1/events/:key**. Authentication: Secret key or dashboard session

Send only the fields to change:

```json
{
  "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`.
`description`, `endsAt`, `timezone`, and `locale` can also be updated or cleared.
`salesCloseAt` and `autoEndAt` take the same values as on create; `null`
removes a time. A time in the past answers `422 sales_close_in_past` (or
`auto_end_in_past`), a close after the end `422 sales_close_after_end`, and
either one on an ended event `409 event_ended`.
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](/server-api/inventory).

## Event poster

The poster is the image on the event's share card when a link to it is posted
in chat or social apps. Without one, SeatLayer draws a card from the event
name and chart.

**PUT /v1/events/:key/poster**. Authentication: Secret key or dashboard session

Send the raw image bytes as the request body, not multipart or base64:

```bash
curl -sX PUT "https://api.seatlayer.io/v1/events/opening-night/poster" \
  -H "authorization: Bearer $SEATLAYER_SECRET_KEY" \
  -H "content-type: image/jpeg" \
  --data-binary @poster.jpg
```

The response is the updated event, `{"meta": {...}}`, with a new `posterPath`.
Each upload gets a new URL, so share previews that cached the old image pick
up the new one.

| Limit | Value | Error |
|---|---|---|
| Size | Up to 5 MB | `413 image_too_large` |
| Format | PNG, JPEG, or WebP, read from the file itself; the `content-type` header is ignored | `415 unsupported_image` |
| Dimensions | Up to 8,000 px per side and 40 megapixels | `422 image_dimensions_unsupported` |
| Body | Must not be empty | `400 empty_body` |

**DELETE /v1/events/:key/poster**. Authentication: Secret key or dashboard session

Removes the poster and returns the event to the generated card. An event with
no poster answers `404 no_poster`.

## Event Configuration binding

An Event Configuration is a versioned production setup for one chart: stage,
screens, barriers, camera platforms, and the seats they take off sale. It is
authored, reviewed, and published in the dashboard, then bound to an event.
Binding to an event is available through this API.

> **Enabled per account**
>
> Event Configurations are a module that SeatLayer turns on per account.
> Without it, binding a configuration answers `403 module_not_enabled`. Reading
> a binding and detaching one work on every account.

**GET /v1/events/:key/event-configuration**. Authentication: Secret key or dashboard session

```json title="200 OK"
{
  "configuration": { "id": "ec_4f1a…", "version": 3 },
  "revision": 2,
  "changedBy": "…",
  "changedAt": 1767200000000,
  "audit": [
    {
      "id": "…",
      "from": null,
      "to": { "id": "ec_4f1a…", "version": 3 },
      "revision": 1,
      "actor": "…",
      "createdAt": 1767100000000
    }
  ]
}
```

`configuration` is `null` when nothing is bound. `audit` lists every attach,
replace, and detach.

**PUT /v1/events/:key/event-configuration**. Authentication: Secret key or dashboard admin

```json title="Bind version 4"
{
  "expectedRevision": 2,
  "configuration": { "id": "ec_4f1a…", "version": 4 }
}
```

Send `"configuration": null` to detach. `expectedRevision` must match the
current `revision`, so two operators cannot overwrite each other.

- Only a `published` version can be bound (`409 version_not_published`).
- The version must match the event's chart revision
  (`409 incompatible_configuration` with `issues`).
- Seats the configuration takes off sale must be free. If any is held or
  booked, nothing changes (`409 configuration_inventory_seat_conflict`).
- A stale `expectedRevision` answers `409 configuration_binding_conflict` with
  the current revision.

Newly killed seats send `seat.blocked`; seats freed by a replaced or detached
configuration send `seat.released`. While a configuration is bound,
[updating the event's chart](#update-an-event-to-the-latest-chart) answers
`409 event_configuration_bound`.

## Ticket releases and on-sale waves

Ticket releases are ordered, event-scoped price windows. Each release can have
a start/end time, category scope, quota, and buyer action. Only `buy` releases
price SeatLayer holds and consume quota; `apply` and `invoice` link to the
organizer's HTTPS workflow and require `actionUrl`.

**GET /v1/events/:key/releases**. Authentication: Secret key or dashboard session

The response returns releases in `position` order. Quota-bearing releases also
include live `consumed` and `remaining` values. `remaining: null` means the
release has no quota.

**PUT /v1/events/:key/releases**. Authentication: Secret key or dashboard session

`PUT` replaces the entire ordered list; it is not a per-release patch. Send at
most 12 releases. Omit `id` for a new release and preserve returned IDs when
editing, because booked and held inventory records the release that priced it.
List order becomes the dense `position` order returned by the server.

```json title="Replace the release list"
{
  "releases": [
    {
      "name": "Early bird",
      "price": 18,
      "previousPrice": 22,
      "quota": 200,
      "startsAt": 1786530600000,
      "endsAt": 1787135400000,
      "action": "buy"
    },
    {
      "name": "Release 2",
      "price": 22,
      "action": "buy"
    }
  ]
}
```

Prices are integer major currency units, matching chart category prices. A
`categoryKey` must exist in the event chart and cannot name a tiered category;
SeatLayer never applies two independent price authorities to one selection.
`startsAt` and `endsAt` are epoch milliseconds. An unscoped release applies to
every non-tiered category.

Whole-list replacement is last-write-wins and does not support automatic
retry or optimistic concurrency. Serialize release editors per event, read the
current list before editing, and confirm the returned list before accepting a
write as complete.

**POST /v1/events/:key/releases/:id/close**. Authentication: Secret key or dashboard session

Closing sets the release's end time to now and returns the full list. It does
not delete the release or erase pricing provenance from existing holds and
bookings. Closing an already closed release is safe, but mutations have no
automatic-retry contract.

## Update an event to the latest chart

Publishing a changed chart never updates an event on its own. Every event
keeps the map it was created or last updated with until you update it, and
the publish response names each linked event that is still on an older map
in `linkedEvents`, with its booked, held and blocked counts and an
`updatePath`: `safe` (nothing to review) or `reviewed` (existing bookings,
holds and blocks are kept). An event whose `reason` is
`configuration_bound` or `group_locked` is updated from its event
configuration or season instead. `refreshedEvents` is always `0`. To move an
event onto the latest published chart, call the explicit route per event:

**POST /v1/events/:key/update-chart**. Authentication: Secret key or dashboard session

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

If the update would drop private channel assignments, inspect the returned
channel summary and repeat deliberately with an audit reason:

```json
{
  "acknowledgeDroppedAssignments": true,
  "reason": "Venue reconfiguration approved by operations"
}
```

If the new map leaves out seats that are sold, held or blocked on the event, the
update fails as a whole and the event keeps its current map:

```json
{
  "error": "seats_would_vanish",
  "code": "seats_would_vanish",
  "kind": "removed",
  "missingLabels": ["A-12"],
  "missingCount": 1,
  "truncated": false,
  "message": "This map leaves out 1 seat that is sold, held or blocked on this event: A-12. The event still uses its current map. To switch, put this seat back in the chart and publish again, or cancel its order, release its hold or unblock it first. To use the new map as it is, create a new event with it."
}
```

| Field | Meaning |
|---|---|
| `kind` | `removed`: the seats are not on the new map. `changed`: the seats are still there but their type or size is different. |
| `missingLabels` | Up to 50 affected seat labels. |
| `missingCount` | How many seats are affected in total. |
| `truncated` | `true` when `missingLabels` lists only some of them. |
| `message` | A plain sentence you can show the organizer as is. |

For `kind: "changed"`, keep those seats as they were, publish again, then
update the event. For `kind: "removed"`, put the seats back in the chart, or
cancel their orders, release the holds and unblock them, then retry. To use the
new map as it is, create a new event with it; the existing event keeps its
orders and its current map.

Archived and deleted events are not mutable.

> **Events in a Season are protected**
>
> A metadata update, archive, or delete that would break an active Season or
> its published Plan answers `409 season_event_locked`. Change the event
> through the [Season workflow](/server-api/seasons/) instead.

## Lifecycle

| Operation | Route | Buyer sales | Organizer reads/actions |
|---|---|---|---|
| Close | `POST /:key/close` | Stopped online; the box office and door keep selling | Available |
| Reopen | `POST /:key/reopen` | Resumed | Available |
| End | `POST /:key/end` | Stopped everywhere, for good | Reports and orders remain available |
| Archive | `POST /:key/archive` | Stopped | Reports remain available |
| Restore | `POST /:key/unarchive` | Stays stopped | Available again |
| Soft delete | `DELETE /:key` | Stopped | Removed from normal event list |

### Close, reopen and end

**POST /v1/events/:key/end**. Authentication: Secret key or dashboard session

Close stops online sales. On a hosted event the box office and the door keep
selling; on an event your app sells, your server's new holds and direct
bookings answer `409 event_closed`. A buyer whose seats were already held when
sales closed can still pay for them. Closing clears `salesCloseAt`, so reopening
never meets a past close time.

End stops every sale, the box office included, and cannot be undone: an ended
event cannot go back on sale. Tickets already sold still check in at the door.
Bookings after the end answer `409 event_ended`.

Every response, and every event read, carries a `sales` block:

```json
{
  "state": "paused",
  "revision": 7,
  "changed": true,
  "sales": {
    "online": "closed",
    "closeAt": null,
    "autoEndAt": 1792792800000,
    "closedAt": 1792787400000,
    "closedBy": "api",
    "venueSelling": true,
    "ended": false
  }
}
```

`online` is `open`, `closed`, `not_open` or `ended`. It reads `closed` as soon
as `salesCloseAt` passes, a moment before the sales state itself changes.
`closedBy` is `schedule` when a set time did it.

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. Restoring an archive never
resumes buyer sales implicitly: it returns the event to the active organizer
list with sales paused. Call `reopen` afterwards to run the normal readiness
gate and resume sales deliberately.

Supported application transitions are:

```text
active -> closed -> active
active or closed -> ended (final)
active or closed -> archived
archived -> active (sales remain paused)
active, closed, or archived -> deleted
```

## Errors to handle

| Status | Code | Action |
|---|---|---|
| `402` | `insufficient_credits` | Top up before creating a new live event. The body carries `message` and `balance` |
| `404` | `chart_not_found` / `not_found` | Check org, workspace, and resource id |
| `409` | `event_exists` | Your workspace already has an event with this slug: use a new slug or replay the original idempotent request |
| `409` | `seats_would_vanish` | The new map leaves out or changes sold, held or blocked seats. Put them back as they were, or free them first, then retry |
| `409` | `season_event_locked` | Amend through the Season workflow or wait until the Season no longer owns the Event |
| `422` | `chart_not_published` | Publish the chart first |
| `422` | `invalid_event_inventory` | Fix the chart validation issue |
| `422` | `workspace_not_found_or_disabled` | Select or enable the workspace |
| `503` | `event_provisioning` | The event's pin and inventory are still landing behind a dashboard `async` create; retry after the `Retry-After` seconds |

## 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](/server-api/inventory),
[booking](/server-api/booking), and [reports](/server-api/reports).

Source: https://docs.seatlayer.io/server-api/events/index.mdx
