---
title: "Seasons API"
description: "Create a Fixed Renewable Season catalogue, publish immutable Plans, run buyer rehearsal, and import incumbent Seat Rights for exact-Plan renewal."
---

> 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.

# Seasons API

The Seasons API is the organizer catalogue for a **Fixed Renewable Season**.
Who owns the sale depends on the season's checkout mode:

- With **SeatLayer checkout** (`checkoutMode: "seatlayer"`), SeatLayer takes
  payment through your connected payment gateway, creates the orders, issues a
  ticket for every date, and makes refunds. You run those orders from this API
  or the dashboard.
- With **your own checkout** (`checkoutMode: "server"`), your platform owns
  identity, pricing, tax, checkout, payment, orders, tickets or passes, and
  refunds. A season whose `checkoutMode` is `null` (not chosen yet) behaves as
  your own checkout.

Either way, SeatLayer owns seating and inventory: occurrence membership, Plan
publication, sales control, same-seat holds, incumbent import, and renewal
offers.

| Who owns this | With SeatLayer checkout | With your own checkout |
|---|---|---|
| Seat ownership and seat rights | SeatLayer | SeatLayer |
| Renewals | SeatLayer runs offers, quote and payment | SeatLayer runs offers; you take payment |
| Give a seat back on one date | SeatLayer | You. These calls answer `409 own_checkout` |
| Tickets and the door | SeatLayer | You |
| App integration | [Holders API](/server-api/holders/) and the season picker | Holders API and the season picker |

Start with the [end-to-end Season integration](/integrations/seasons/) for the
complete lifecycle and responsibility boundary. Use the
[Season picker](/buyer-sdk/seasons/) for buyer UI; this page owns exact trusted
operations and recovery behavior.

Buyer access sessions, trusted hold inspection, booking, cancellation, holder
import, and renewal offers are on this page. Browser `/pub/seasons/*` routes
stay picker-only and are not server-SDK operations. A Seat Right is a durable
fence, not a [checkout hold](/server-api/how-seat-holds-work/). A buyer
rehearsal or checkout test is advised before opening sales, not required:
until one has passed, opening sales warns `checkout_test_missing`. A season
sold through SeatLayer checkout has no rehearsal to run and is never warned.

Every released secret-key route on this page uses a matching `sk_test_…` or
`sk_live_…` key. Keep that key on your server. Dashboard availability is a
separate release boundary and does not change the public SDK contract.

> **Current production surface**
>
> Seasons are public through the browser picker, REST API, and all seven server
> SDKs, and organizers can manage them from the dashboard's **Seasons** page.
> Native Season pickers are not supported. [Season Best
> Available](#season-best-available) picks the same seats on every date with a
> buyer session token.

> **All 90 operations in every server SDK**
>
> All seven official server SDKs (Node.js, Python, PHP, Java, Go, Ruby, and
> .NET) send all 90 Season operations at `0.9.0`: the 48 that `0.8.0` already
> had, plus the [42 added in `0.9.0`](#operations-added-in-090). That includes
> season seats, occurrence return and reclaim, the holder API, the reports,
> and both CSV downloads. Language method names differ; operation coverage
> does not.

> **Where REST is ahead of 0.9.0**
>
> A few REST request fields are not in every `0.9.0` SDK: `planActivationId`
> and `purpose` on a buyer session, the `planActivationId` query on the
> occurrence list, and `planActivationId` on an amendment. Each matters once a
> season has more than one published Plan, or for a rehearsal session.
> [REST fields not in every SDK](#rest-fields-not-in-every-sdk) says which SDKs
> have each one. A season's `inventoryMode` is in all seven.
> React Native, Flutter, iOS, and Android do not expose a native Season v1
> picker.

| Released surface | Package or coordinate |
|---|---|
| REST | `https://api.seatlayer.io/v1/seasons` |
| Node.js | `npm install @seatlayer/server@0.9.0` |
| Python | `pip install seatlayer==0.9.0` |
| PHP | `composer require seatlayer/seatlayer-php:0.9.0` |
| Java | `io.seatlayer:seatlayer-java:0.9.0` |
| Go | `go get github.com/seatlayer/seatlayer-go@v0.9.0` |
| Ruby | `gem install seatlayer -v 0.9.0` |
| .NET | `dotnet add package SeatLayer --version 0.9.0` |

Season setup, operations, holder and report routes have a durable per-key
budget of 600 requests per minute and return `429 rate_limited`, `Retry-After`,
and standard rate-limit headers when exhausted. Selling has no budget: buyer
sessions, hold reads, book, booking reads and cancel, and renewal intent,
checkout and commit are never refused for rate. Browser and dashboard routes
use separate budgets.

## Released 0.9.0 API map

These 48 operations are in every server SDK from `0.8.0` on.

| Task | Method and route |
|---|---|
| List Seasons | `GET /v1/seasons` |
| Validate Event / Performance Group compatibility | `POST /v1/seasons/validate` |
| Create a draft | `POST /v1/seasons` |
| Read one Season | `GET /v1/seasons/:key` |
| Rename a draft, or set checkout mode and audience | `PATCH /v1/seasons/:key` |
| Discard a draft | `DELETE /v1/seasons/:key` |
| Activate structure | `POST /v1/seasons/:key/activate` |
| Close structure | `POST /v1/seasons/:key/close` |
| Archive a closed Season | `POST /v1/seasons/:key/archive` |
| Recover lifecycle | `GET /v1/seasons/:key/lifecycle/:operationId` |
| Add a draft Plan | `POST /v1/seasons/:key/plans` |
| Read a Plan | `GET /v1/seasons/:key/plans/:planKey` |
| Publish a Plan | `POST /v1/seasons/:key/plans/:planKey/publish` |
| Supersede a Plan | `POST /v1/seasons/:key/plans/:planKey/supersede` |
| Open / pause / resume / end sales | `/v1/seasons/:key/sales/open` · `pause` · `resume` · `end` |
| Duplicate test configuration to live | `POST /v1/seasons/:key/duplicate-to-live` |
| Mint / list / revoke browser sessions | `/buyer-access-sessions` |
| Inspect the opaque Season hold | `GET /:key/holds/:operationId` |
| Book the hold | `POST /:key/holds/:operationId/book` |
| Retrieve / cancel a booking | `GET /:key/bookings/:actionId` · `POST /:key/bookings/:actionId/cancel` |
| Import incumbent holders | `POST /v1/seasons/:key/imports` · `GET /imports/:importId` |
| Generate / list renewal offers | `POST /v1/seasons/:key/renewal-offers` · `GET /renewal-offers` |
| Read / inspect / extend an offer | `GET /renewal-offers/:offerId` · `GET /inspect` · `POST /extend` |
| Commit / decline / release | `POST /commit` · `POST /decline` · `POST /release` |
| List occurrences | `GET /v1/seasons/:key/occurrences` |
| Amend / list amendments | `POST /amendments` · `GET /amendments` |
| Reports / operations / support | `GET /reports` · `GET /operations` · `GET /support-lookups` |
| Outbox / replay | `GET /outbox` · `POST /outbox/:occurrenceId/replay` |
| Redacted audit / support export | `GET /audit` · `GET /export` |

Activation does not publish a Plan. Publication does not open sales. Audience
stays `embed_only`.

<a id="rest-operations-beyond-the-48"></a>

### Operations added in 0.9.0

These 42 operations are in all seven server SDKs from `0.9.0`. `0.8.0` has none
of them, so on `0.8.0` call them over HTTP with your secret key. The
[language references](/server-sdk/) give each SDK's method names. The rows from
**List holders** down are the
[holder API](#holders-orders-renewal-emails-and-reports).

| Task | Route |
|---|---|
| Bring holders from a previous season | `POST /v1/seasons/:key/imports/from-season` |
| List performances (works on a draft) | `GET /v1/seasons/:key/performances` |
| Create or attach performances in a draft | `POST /performances` · `POST /performances/attach` |
| Remove a performance from a draft | `DELETE /performances/:eventKey` |
| Rename, re-date, or delete a draft Plan | `PATCH /plans/:planKey` · `DELETE /plans/:planKey` |
| Publish in one call | `POST /v1/seasons/:key/publish` |
| Run and list checkout tests | `POST /checkout-tests` · `GET /checkout-tests` |
| Set and list package prices | `PUT /plans/:planKey/prices` · `GET /prices` |
| Add a performance to a published Plan | `POST /plans/:planKey/performances` |
| Remove a performance from a published Plan | `DELETE /plans/:planKey/performances/:eventKey` |
| Mark a performance as taken place | `POST /performances/:eventKey/past` |
| Refund every order of a cancelled date, as a job | `POST /performances/:eventKey/refunds` |
| Release every lapsed renewal offer's seats, as a job | `POST /renewal-offers/release-lapsed` |
| List bulk jobs, or read one with its failed items | `GET /jobs` · `GET /jobs/:jobId` |
| Return one booked occurrence to ordinary Event inventory | `POST /occurrences/:eventKey/returns` |
| Reclaim a still-free occurrence return | `POST /occurrences/:eventKey/reclaims` |
| List holders | `GET /v1/seasons/:key/holders` |
| Refund, cancel, or cancel one date of a holder's order | `POST /orders/:orderId/refund` · `POST /orders/:orderId/cancel` · `POST /orders/:orderId/dates/:eventKey/cancel` |
| Email an order's tickets again | `POST /orders/:orderId/resend` |
| Renewal links, payments and emails per offer | `GET /renewal-hosted` |
| What a renewal costs, and a SeatLayer checkout for it with no hosted page | `GET /renewal-offers/:offerId/quote` · `POST /renewal-offers/:offerId/checkout` |
| Record a holder's intent for a phone or box office renewal | `POST /renewal-offers/:offerId/intent` |
| New renewal link, holder contact, email again | `POST /renewal-offers/:offerId/link` · `POST /contact` · `POST /resend` |
| Email renewal invitations and reminders | `POST /renewal-notices` |
| Sales and free-seat reports | `GET /reports/sales` · `GET /reports/seats` |
| Holder and order downloads | `GET /reports/holders.csv` · `GET /reports/orders.csv` |
| Season seats sold per package and date | `GET /seat-counts` |
| Set season seats aside, read them, release them to single sale | `POST /block` · `GET /block` · `POST /block/release` |

### REST fields not in every SDK

Eight of the 90 operations have REST fields that some or all `0.9.0` SDKs do not
name. Python, PHP, Java, Go, Ruby, and .NET return these answers as decoded
JSON, so they carry every response field. Node.js returns typed objects, and
the types below leave some fields out.

| Operation | REST field | In `0.9.0` |
|---|---|---|
| Create buyer session | Request `planActivationId`, `purpose`, `buyerEmail` and `buyerName` | No SDK has a parameter for any of them. Send them over REST. |
| List buyer sessions | Row `purpose`, also on the create answer | Node.js's `SeasonBuyerAccessSession` and `SeasonBuyerAccessReveal` types have `planActivationId` but not `purpose`. The other six return it. |
| Validate buyer rehearsal | Response `planActivationIds` and `activationEvidence` | Node.js's `SeasonBuyerRehearsalResult` type has neither. The other six return both. |
| List occurrences | Query `planActivationId`, and the answer's top-level `planActivationId` | No SDK sends the query. Node.js's return type has no top-level `planActivationId`. |
| Create amendment | Request `planActivationId` | PHP and Java send it. Node.js, Python, Go, Ruby, and .NET have no parameter for it. |
| Create amendment; create performances; add or remove a performance in a published Plan | Request `notifyCustomers` (a query on the removal), and the answer's `customersNotified` ([Email the date's customers](#email-the-dates-customers)) | No SDK sends `notifyCustomers`. Send it over REST. Node.js's types have no `customersNotified`; the other six return it. |

Everything else in these operations is in all seven. Every SDK sends amendment
kinds `postpone` and `cancel` with `refund` and `reason`, reads amendment rows
with those kinds, and sends `successorPlanActivationId` on renewal offers. Above
100 contracts, renewal offers answer `202` with a `renewal_run` job, and every
SDK returns that answer.

The [version-pinned language references](/server-sdk/) are authoritative for
the exact method spelling and request shape. The OpenAPI document describes
REST, not one package version.

> **More than one published Plan**
>
> A Season can keep several immutable Plans published. In `0.9.0`, every SDK
> takes the activation where a call names one Plan: `successorPlanActivationId`
> on renewal offers and holder imports, and `planActivationId` on booking
> cancel, occurrence return, and reclaim. Choosing a Plan for a buyer session,
> the occurrence list, or an amendment is not in every SDK (see the table
> above). Publishing a new Plan is allowed only while sales are `closed` or
> `ended`; otherwise it returns `409 sales_not_ended`. A browser session is
> always bound to one exact Plan activation. `planActivationId` is required when
> more than one Plan is published, while omission remains compatible for a
> single published Plan. An unknown or superseded activation returns `409
> plan_not_published`. Every successful new publication clears rehearsal
> readiness, so opening sales warns again until a checkout test or rehearsal
> passes for the new Plan.

## Validate before creation

Preflight is read-only and returns exact incompatible Event identity, field,
expected/actual values, and remediation. It accepts direct Event keys, active
Performance Group keys, or both:

```http title="compatibility preflight"
POST /v1/seasons/validate HTTP/1.1
Authorization: Bearer sk_test_••••••••
Content-Type: application/json

{
  "sourcePerformanceGroupKeys": ["pg_spring_series"],
  "eventKeys": ["ev_bonus_night"]
}
```

Performance Group sources must be active. Creation freezes the group's
activation identity and exact Event membership on the Plan. Publication refuses a source that has since changed or
closed; it never silently adopts new membership.

### Workspaces

A season lives in the workspace of its dates, and every date must be in the
same one. Your secret key reaches every workspace of your organization:

- Validate and create take the workspace from the dates: the first Event's, or
  the first Performance Group's. To name it yourself, send `workspaceId`; every
  date must then be in it.
- A date in another workspace answers `workspace_mismatch`, naming that Event,
  the workspace expected and the one it is in. A `workspaceId` that is not an
  active workspace of your organization answers `404
  workspace_not_found_or_disabled`.
- The validate answer says which workspace it checked (`workspaceId`), and the
  season carries its `workspaceId`.
- `GET /v1/seasons` lists the seasons of your default workspace, as
  `GET /v1/events` lists its events. Pass `?workspaceId=` to list another
  workspace's. Reading, changing and selling a season by its key works in any
  workspace.

## Create a draft Season

```http title="HTTP request"
POST /v1/seasons HTTP/1.1
Authorization: Bearer sk_test_••••••••
Idempotency-Key: 2026-series-draft
Content-Type: application/json

{
  "name": "2026 series",
  "edition": "2026–27",
  "eventKeys": ["ev_night_1", "ev_night_2"]
}
```

`name` is required (1–120 characters). `edition` is optional. Selection may use
`eventKeys`, `sourcePerformanceGroupKeys`, or both. Each fixed Plan must contain
2–25 distinct Events that share organization, [workspace](#workspaces), mode,
chart, currency, venue, and timezone. Channel-restricted inventory is excluded from v1. The
seasons module must be enabled. A season made before the 25-date limit keeps up
to 50 dates and works as before; a date can be added to it only while its package
stays at 25 dates or fewer.

`currency` is a child-Event compatibility constraint, not the Season package
currency. SeatLayer never derives the package price from Event category or tier
amounts.

`201` returns `{ season }` with `structureState: "draft"`, `salesState: "closed"`,
`audience: "embed_only"`, and at least one draft Plan. Retry create with the
same [idempotency key](/server-api/idempotency-and-conflicts/) to replay the
original body.

`DELETE /v1/seasons/:key` succeeds only for a draft.

### Create new performances in a draft Season

When the Season should create ordinary Events rather than attach existing ones,
pass the venue region with the performance request:

```http title="create performances near the venue"
POST /v1/seasons/sea_123/performances HTTP/1.1
Authorization: Bearer sk_test_••••••••
Content-Type: application/json

{
  "titlePattern": "Autumn night {n}",
  "firstStartsAt": 1792346400000,
  "timezone": "Europe/Amsterdam",
  "repeat": "weekly",
  "count": 3,
  "region": "western-europe"
}
```

`region` follows the same [11-region table and first-placement
rules](/server-api/event-regions/) as ordinary Event creation. Omit it to use
the workspace default; pass `asia-pacific` for venues in India.

Additional immutable fixed Plans may be added only while the Season is still a
draft. Every successful addition atomically advances the Season revision and
its distinct-Event union identity. Activation fences catalogue membership.
After activation, a performance joins or leaves a published Plan only through
the amendment routes (`POST /plans/:planKey/performances` and
`DELETE /plans/:planKey/performances/:eventKey`), and each change is recorded
as an amendment.

### Add or remove a date in a published package

**POST /v1/seasons/:key/plans/:planKey/performances**. Authentication: Secret key
**DELETE /v1/seasons/:key/plans/:planKey/performances/:eventKey**. Authentication: Secret key

Both change every holder of the package, one holder at a time.

**Adding a date** books each holder's seats on it, where those seats are free.
A holder who bought through SeatLayer checkout gets a ticket for each seat on
the new date. A seat that is taken is listed in `conflicts` and that holder is
left as they were. Each seat booked uses a credit
([Seasons pricing](/billing/pricing/#seasons)). The credits are checked first:
when the wallet the season uses can't cover the seats, nothing changes and the
answer is `402 insufficient_credits` with `wallet`, `required` and `available`.
`available` is the balance less the tickets open checkouts are holding, and
less the seats date changes booked in the last 15 minutes that may not be
charged yet. Creating several dates in one call checks them together.

{/* sample-guard: skip trimmed response: … stands for fields and items left out */}
```json title="200"
{
  "performances": [ … ],
  "extended": 412,
  "conflicts": [{ "label": "B-7", "bookingRef": "ord_91c2…", "reason": "seat_taken" }],
  "ticketsIssued": 820,
  "stopped": [],
  "job": { "jobId": "sam_…", "kind": "date_added", "state": "completed", "total": 413, "done": 412, … }
}
```

**Removing a date** first voids each holder's tickets for it, then puts their
seats back on sale. A ticket already scanned is refused: it stays checked in,
its seat stays held, and the holder is listed in `stopped` with
`"reason": "ticket_scanned"` and the seats in `scannedLabels`. Their other
tickets on the date are voided and those seats go back. `released` counts the
holders taken off the date, `seatsReleased` the seats and `ticketsVoided` the
tickets. Removing a date refunds nobody: to refund, cancel the date. Credits
stay spent. A date this package never held is `404 occurrence_not_in_plan`;
removing a date again after it has gone answers the same `200`.

**Email the holders.** Send `"notifyCustomers": true` with an add (also with
`attachToPlanKeys` on `POST /v1/seasons/:key/performances`), or
`?notifyCustomers=true` with a removal. Once the change's job has ended,
SeatLayer emails each holder it reached: on an add, each holder who got a
ticket for the new date; on a removal, each holder whose ticket for it stopped
working, a holder stopped on a scanned ticket included. It is off by default,
and the answer's `customersNotified` says whether the holders are emailed. See
[Email the date's customers](#email-the-dates-customers).

A large package answers `202` with `Retry-After` while its holders are still
being changed, with the progress in `job`. Send the same request again until it
answers `200`. The change is named by the season, package and date, so the
same request always continues the same change.

One date change runs per season at a time. A second one, for any date, answers
`409 date_change_in_progress` with the running `job`, and changes nothing; send
it again once that job has ended.

A date that has already started is refused with `422 date_in_past`, a date that
was cancelled with `409 performance_cancelled`, and any date on a closed season
with `409 season_closed`. A date at the same minute as one the season already
has is refused with `409 date_already_in_season`, which names that date's
`eventKey`; a cancelled date no longer holds its time.

A holder the job could not change after its retries is listed in `stopped`,
with their `bookingRef`, their `orderId` when they bought through SeatLayer
checkout, and a `reason`. `tickets_failed` means the seat on the new date is
booked but the tickets could not be issued. Holders that failed are listed
first, at most 500; `stoppedTruncated: true` says there are more.

A job that ended badly answers `200` once, as it ended: `job.state` is `failed`
(the job itself could not finish), or holders are listed in `stopped`. Sending
the same request again after that runs what failed again, and issues any
tickets that were missing; what worked is not repeated.

## Node.js quickstart

Install the current public server SDK:

```bash
npm install @seatlayer/server@0.9.0
```

```ts title="test-mode catalogue and lifecycle"
import { SeatLayer } from '@seatlayer/server';

const seatlayer = new SeatLayer({
  secretKey: process.env.SEATLAYER_TEST_SECRET_KEY!,
});

const compatibility = await seatlayer.seasons.validateSeason({
  sourcePerformanceGroupKeys: ['pg_spring_series'],
});
if (!compatibility.valid) throw new Error(compatibility.issues[0]?.remediation);

const { season: draft } = await seatlayer.seasons.createSeason({
  name: '2026 series',
  edition: '2026–27',
  sourcePerformanceGroupKeys: ['pg_spring_series'],
}, { idempotencyKey: '2026-series-draft' });

const active = await seatlayer.seasons.waitForSeasonLifecycle(
  await seatlayer.seasons.activateSeason(draft.key, draft.revision),
  { timeoutMs: 30_000 },
);
const firstPlan = active.season.plans[0]!;
await seatlayer.seasons.waitForSeasonLifecycle(
  await seatlayer.seasons.publishSeasonPlan(
    active.season.key,
    firstPlan.key,
    active.season.revision,
  ),
  { timeoutMs: 30_000 },
);
```

This quickstart uses calls the Node.js SDK has had since `0.8.0`. Occurrence
return and reclaim below are in every SDK from `0.9.0`. Some multi-Plan request
fields below are not in every SDK; see
[REST fields not in every SDK](#rest-fields-not-in-every-sdk).

The SDK polls only the retained `Location` / lifecycle operation identity
returned by `202 Accepted`, honors `Retry-After`, and stops at the caller's
timeout. Use `sk_test_…` credentials and test Events while integrating.

## Activate, publish, and sales

```http title="activate"
POST /v1/seasons/sea_…/activate
Authorization: Bearer sk_test_••••••••
Content-Type: application/json

{ "expectedRevision": 1 }
```

Activation is structural. The published Plan is a separate machine:

```http title="publish"
POST /v1/seasons/sea_…/plans/spl_…/publish
Authorization: Bearer sk_test_••••••••
Content-Type: application/json

{ "expectedRevision": 2 }
```

After publication, `salesState` is still `closed`. Publishing any additional
Plan also resets rehearsal readiness. Opening sales:

```http title="open sales"
POST /v1/seasons/sea_…/sales/open
Authorization: Bearer sk_test_••••••••
Content-Type: application/json

{ "expectedRevision": 3 }
```

Opening sales needs an active Season, a published package and a chosen
checkout mode: otherwise `409 coupled_lifecycle`, `409 plan_not_published` or
`409 checkout_mode_not_chosen`. On SeatLayer checkout, the first open also needs
a package price for every category each published package's dates sell:
otherwise `409 prices_missing`, whose `packages` lists each package and the
categories to price, and whose `fixUrl` opens the dashboard's Sell tab. A resume
after a pause is not checked. A buyer rehearsal or checkout test is advised,
not required. Until one has passed, the answer is still `200`, with
`"warnings": [{ "code": "checkout_test_missing", "message": "…" }]`; the
warning goes once a [checkout test](#run-a-checkout-test) passes or a
rehearsal is validated. A season sold through SeatLayer checkout
(`checkout_mode: "seatlayer"`) has none of your integration to prove, so it is
never warned. Pause, resume, and end use the same
`expectedRevision` body on `/sales/pause`, `/sales/resume`, and `/sales/end`.

### Run a checkout test

**POST /v1/seasons/:key/checkout-tests**. Authentication: Secret key
**GET /v1/seasons/:key/checkout-tests**. Authentication: Secret key

A checkout test checks that a buyer can hold seats on every date of a package.
In one call it makes a short buyer session, holds seats that are free on every
date, releases them and ends the session. It never books and never charges.
**Run test** on the season's **Overview** in the dashboard runs the same test.

```http title="run a checkout test"
POST /v1/seasons/sea_…/checkout-tests
Authorization: Bearer sk_test_••••••••
Content-Type: application/json

{ "planKey": "spl_…", "quantity": 2 }
```

Both fields are optional. `planKey` is the package to test; without it, the
first published package. `quantity` is how many seats to hold, 1 to 4; the
default is 2.

```json title="200"
{
  "test": {
    "id": "sct_…",
    "status": "passed",
    "startedAt": 1790000000000,
    "finishedAt": 1790000001400,
    "planKey": "spl_…",
    "seats": ["A-1", "A-2"],
    "steps": [
      { "step": "session", "ok": true, "durationMs": 40 },
      { "step": "availability", "ok": true, "durationMs": 60 },
      { "step": "hold", "ok": true, "durationMs": 820 },
      { "step": "release", "ok": true, "durationMs": 310 }
    ]
  }
}
```

The answer is `200` whether the test passes or fails. A step that fails reads
`ok: false` with a `detail`, `status` is `failed`, and the steps after it read
"Skipped after an earlier step failed". `seats` are the first free seats on
every date, in label order.

- **Sales closed:** the test holds as a rehearsal. **Sales open:** it holds as
  a sale. **Paused or ended:** the `hold` step fails.
- A test that passes clears the `checkout_test_missing` warning on
  [opening sales](#activate-publish-and-sales).
- `GET /checkout-tests` lists the last 20 tests, newest first, as
  `{ "tests": [...] }`.
- `Idempotency-Key` is optional. The same key with the same body answers the
  first result and runs no new test.

| Error | Meaning |
|---|---|
| `409 season_not_active` | Activate the season first |
| `409 plan_not_published` | No package is published yet |
| `404 plan_not_found` | No package has that `planKey` |
| `422 invalid_plan_key` · `422 invalid_quantity` | `planKey` is empty or not a string, or `quantity` is not a whole number from 1 to 4 |

### Single tickets for each date

A season sells its seats as a package. `singleTickets` says whether each date
also sells its own single tickets beside it. It is `false` by default, "Season
only": nobody can buy one date on its own, from a buyer page, a picker or your
own server. A date can't go on sale on its own while it is in the season. A
date that was already selling when it joined (an Event your server created
starts `live`) keeps selling until the season's sales open. Then its own
sales stop: a live date pauses, and a test-mode date's test window closes.
The answer lists those dates in `singleTicketDates.closed` (it has no
`singleTicketDates` when no date was still selling), and a date added
while the season is on sale stops the same way. Until then,
`season.singleTicketsStillSelling` lists the dates still selling their own
tickets. Holds on a stopped date answer `409 event_closed`. The season's own
holds and bookings on it go on as before.

Set it on create (`POST /v1/seasons` with `"singleTickets": true`) or later:

```http title="sell single tickets too"
PATCH /v1/seasons/sea_…
Authorization: Bearer sk_test_••••••••
Idempotency-Key: 6f1c…
Content-Type: application/json

{ "expectedRevision": 5, "singleTickets": true }
```

With it on, when the season's sales open (or resume), or when it is turned on
while they are open, each date that has not started opens its own sales
through that date's own readiness checks, as
[going on sale](/server-api/event-checkout/#going-on-sale) does. The answer says what happened:

```json
{
  "season": { "key": "sea_…", "singleTickets": true, "…": "…" },
  "singleTicketDates": {
    "direction": "open",
    "opened": ["ev_1", "ev_2"],
    "closed": [],
    "notOpened": [{ "eventKey": "ev_3", "name": "Night 3", "salesState": "setup", "unmet": ["buyerCheckout"] }],
    "jobId": null
  }
}
```

A date in `notOpened` lacks the checks named in `unmet`, the names
`GET /v1/events/:key/sales/readiness` uses. A paid live date names
`preflight` until the season has had a test purchase. One covers every date
of the season: place it on any date while that date is `testable` and record
it with `POST /v1/events/:key/sales/preflight`, as
[going on sale](/server-api/event-checkout/#going-on-sale) describes. The
season's other dates waiting for one then open, and each records the same
test purchase, through the same payment provider. Fix the rest
and open the date's sales from its own page, or send `singleTickets: true`
again: every date not yet open is tried again. While the
season is on sale, `GET /v1/seasons/:key` lists the dates still not selling
their own tickets in `season.singleTicketsNotOpen`. A date added while the
season sells single tickets opens the same way, once its job has booked every
holder's seat. A season with more than 12
upcoming dates opens them by a `season_singles` job instead: `jobId` names it
([Follow a job](#follow-a-job)), and each item's result says how its date went.
Each date of the job looks at the season first, so a later change the other
way wins: turned off before the job ends, no date is left selling singles (its
item says `superseded`). In the rare case the job cannot start, the change
still stands, `singleTicketDates.jobRefused` says why, and the dates wait in
`season.singleTicketsNotOpen` until you send `singleTickets: true` again.

A request whose answer was lost can be sent again exactly as it was, with the
same `expectedRevision` (and `Idempotency-Key`, if it had one): the season is
not changed twice, and the dates are opened or stopped as that change asked.

To turn single tickets on later by themselves, say two weeks after the season
goes on sale, send the time instead:

```http title="single tickets from 1 December"
PATCH /v1/seasons/sea_…
Authorization: Bearer sk_test_••••••••
Idempotency-Key: 9a2e…
Content-Type: application/json

{ "expectedRevision": 5, "singleTicketsAt": "2026-12-01T10:00:00+01:00" }
```

At that time `singleTickets` turns on, once, exactly as sending
`"singleTickets": true` then would: with the season on sale, each date opens
its own sales through its readiness checks, by a `season_singles` job. The
season read shows the time in `season.singleTicketsAt` (epoch milliseconds,
`null` when none is set), and its revision doesn't change when you set one.

- Send a new time to move it, or `"singleTicketsAt": null` to cancel it.
- Turning single tickets on by hand replaces the time: it never turns them on
  again, even if you turn them off before it.
- The time must be still to come and within two years (`422
  invalid_single_tickets_at`). With single tickets already on, a time is
  refused with `409 single_tickets_on`.

Turning it off pauses each date's single sales (a test-mode date's test window
closes); sent again while the season is on sale, it stops any date still
selling. Orders already made stay as they are. Season holders are never
affected either way: their seats stay held for them on every date, so only
seats the season has not taken sell as singles. Pausing or ending season sales
doesn't stop single tickets. Turn `singleTickets` off to stop them.

Close structure only when sales are not open:

```http title="close"
POST /v1/seasons/sea_…/close
Authorization: Bearer sk_test_••••••••
Content-Type: application/json

{ "expectedRevision": 4 }
```

Close starts a durable close/drain decision: already accepted operations remain
retrievable and recoverable, while fresh sale work is refused. The returned
operation becomes terminal when the structure reaches `closed`.

`POST /v1/seasons/:key/archive` accepts only a closed Season and preserves
sales as closed. `GET /v1/seasons/:key/lifecycle/:operationId` returns the
activation, close, archive, or Plan-publication operation recorded on the
Season.

Activation, close, archive, Plan publication, and Plan supersession retain one
audit checkpoint and one semantic webhook occurrence per immutable action.

## Occurrence amendments and operational support

`POST /v1/seasons/:key/amendments` records either an identity-preserving
reschedule or an explicit replacement/cancellation exception. It never changes
activated Plan membership. Each successful mutation gets an immutable
`revision` and retains deterministic `contractOutcomes` and
`allocationOutcomes`. The outcomes are durable: list and retrieve always return
them.

`GET /reports` combines live Season state with allocation totals and
receiver-attempt health. An occurrence is counted as delivered only after at
least one subscribed receiver returns `2xx`. This is an inventory/operations
report, not revenue, payment, refund, attendance, or utilization reporting.

`POST /outbox/:occurrenceId/replay` resends the retained payload with the same
business `occurrenceId`. It increments replay metadata once the resend is
accepted and does not mark the occurrence delivered. Receiver deduplication remains required.

`GET /support-lookups` accepts either `bookingRef` or `holderRef`, returns the
correlated inventory records plus the request ID, and makes no refund claim.
`GET /audit` returns bounded redacted activity. `GET /export` returns
`season-support-export.v1`, a bounded JSON snapshot with catalogue identity,
Plans, amendments, allocations, report, and audit; `truncated` flags disclose
whether either bounded collection has more rows.

Top-level Season listing is cursor-paginated. Occurrences are complete within
the public contract: up to 25 dates, and up to 50 for a season made before the
25-date limit (7 Nov 2026). Buyer-session history is latest 100.
Renewal offers page through every offer by cursor (see below). Amendment lists
return latest 100 plus `truncated`; operations return latest 50 plus
`truncated`; outbox returns latest 100 plus
`truncated`. Report and outbox totals use the full retained aggregate, and an
older omitted outbox occurrence remains replayable by its exact ID.

## Adult and child prices

A package can price each category once per price type: `adult`, `child`,
`concession`, `senior` and `student`. A price without `priceTypeKey` is
`adult`, so a package priced before price types sells every seat as adult.
Your staff set these prices on the season's Sell tab in the dashboard, and your
server sets them with this route:

```http
PUT /v1/seasons/sea_…/plans/spl_…/prices
Authorization: Bearer sk_test_••••••••

{ "prices": [
  { "categoryKey": "stalls", "unitPrice": 18000 },
  { "categoryKey": "stalls", "priceTypeKey": "child", "unitPrice": 9000 }
] }
```

`unitPrice` here is an integer in minor units (cents, pence, paise; the whole
unit for zero-decimal currencies such as JPY) and is the price of one seat for
the whole package, not for one date. `18000` in GBP is £180.00. A decimal or a
string answers `invalid_unit_price` (422). This differs from event prices and
event holds, which use major units (`75` is £75.00).

The call replaces the package's whole price table: a category or price type
you leave out loses its price. To change one price, send the full table with
that one value changed. An empty `prices` list clears every price.

`GET /v1/seasons/:key/prices` answers each price with its `priceTypeKey` and
`priceTypeLabel`. `invalid_price_type` (422) refuses a key that is not on the list.

A buyer does not choose a price type. The season page at
`app.seatlayer.io/s/SEASON_KEY` lists each type's price, but every seat a buyer
holds there, or with the released [`SeasonPicker`](/buyer-sdk/seasons/), is
`adult`, so give each category an adult price. `GET
/v1/seasons/:key/holds/:operationId` shows each seat's `priceTypeKey`. Checkout
prices each seat by its type, and the order line keeps the type.

A renewal keeps the type the seat was sold as: a child seat renews at the
child price. `GET /v1/seasons/:key/renewal-offers/:offerId` lists `seats`
with their `priceTypeKey`. A holder imported without a SeatLayer order renews
as adult. `season.order.paid` names each seat's type in `lines`.

Seasons carry no booking fee.

## Buyer session, inspect, book, cancel

```http title="mint"
POST /v1/seasons/sea_…/buyer-access-sessions
Authorization: Bearer sk_test_••••••••
Content-Type: application/json

{
  "allowedOrigin": "https://tickets.example.com",
  "includePublic": true
}
```

Every server SDK sends this request. `201` reveals the `bss_…` token once and
returns the server-inferred `planActivationId` for the single published Plan,
plus Origin, mode, environment, quantity limit, and buyer reference metadata.
The token is not a refresh token. v1 requires `includePublic: true`; a false
value does not create a private scope.

> **Session fields no SDK names**
>
> No `0.9.0` server SDK has a parameter for `planActivationId`, `purpose`,
> `buyerEmail` or `buyerName` on this request, so send them over REST. Multiple
> published Plans require an exact activation, and `purpose` distinguishes sale
> from rehearsal. `buyerEmail` and `buyerName` fill in SeatLayer checkout's card.

When your site knows who the buyer is, such as a signed-in member, send
`buyerEmail` and `buyerName` with the mint. SeatLayer checkout's card then
opens with them filled in, so the buyer does not type them again. Both are
optional and can be `null`:

| Field | Rule |
|---|---|
| `buyerEmail` | Must contain `@`, at most 320 characters, trimmed. Anything else returns `422 invalid_email`, as SeatLayer checkout does. |
| `buyerName` | Trimmed. A blank name counts as none. |

They only prefill the card: the email the buyer submits at checkout decides the
order. The `201` response and the session list do not return them. Only this
session's season read does, as `buyer` (below). A session the browser mints
itself carries none.

The buyer's season read, `GET /pub/seasons/:key`, names the club, so a buyer
page shows the club and never SeatLayer. It carries the organization's Brand
settings exactly as the event page's read does:

| Field | Value |
|---|---|
| `organizerName` | The organization's name. `null` while it is blank or still the name it got at signup. |
| `orgLogoUrl` | The Brand logo's public URL. `null` when the Brand has no logo. |
| `orgAccent` | The Brand colour, as a hex string. `null` when none is set. |

A Brand change reaches the read within a minute.

Sent with no session at all (no `Authorization` header), the same read lists
the season's dates for your own page: every date of its published packages,
earliest first, each with `eventKey`, `name`, `startsAt`, `past` and
`cancelled`. It answers only a season open to the web (`audience: "public"`),
as the package read below does, and carries no package of its own
(`planActivationId: null`; `planActivationIds` names every published package).
A buyer session's read is unchanged. A token that has expired or is wrong still
answers as before; it is never read as no session.

The same read carries `salesState`, the season's sales state: `open`, `closed`
(sales not opened yet, or between seasons while holders renew), `paused` or
`ended`. Only `open` is on sale.

It also carries `buyer`, the buyer your server named when it minted the
session that makes the read: `{ "email": …, "name": … }`, either of which can
be `null`. It is `null` when the mint named nobody, and on a session the
browser minted itself. A session never sees another session's buyer.

The package read, `GET /pub/seasons/:key/prices`, lets a page show every
package before the buyer picks one. Each published package carries its prices
and its dates still to come:

| Field | Value |
|---|---|
| `datesToCome` | How many of the package's dates still count: a date marked past or cancelled leaves the count, as it does in the season read. |
| `firstDateAt` | The first of those dates, in epoch milliseconds. `null` when none is left or none has a time. |
| `lastDateAt` | The last of those dates, in epoch milliseconds. `null` the same way. |

A season open to the web (`audience: "public"`) answers this read with no
session. An `embed_only` season answers it only to a request that sends one of
that season's buyer access sessions (`Authorization: Bearer bss_…`), the
session your server mints for the picker. Without one, or with another
season's, an expired or a revoked session, the read answers
`404 not_found`, as for a season that does not exist.

Use the [JavaScript, React, Vue, or Angular Season picker](/buyer-sdk/seasons)
with that token against `/pub/seasons/:key`. After the picker
returns an opaque handoff, inspect then book from your server:

All four web `SeasonPicker` packages expose the released browser baseline. All
seven server SDKs at `0.9.0` send all 90 Season server operations, occurrence
return and reclaim included. Five of them have REST fields that not every SDK
names; see [REST fields not in every SDK](#rest-fields-not-in-every-sdk). Safe
session adoption is the browser route `POST /pub/seasons/:key/session/adopt`,
not a server SDK operation. A backend integration remains necessary with your
own checkout:
the secret-key server must inspect the opaque hold, apply the host's trusted
price and payment decision, and book it.

Book within 15 minutes of the hold. A hold made with a buyer session lasts 15
minutes, whoever minted the session, and the API has no call that extends it;
see [how long a hold lasts](#when-a-hold-cant-finish).

A hold that cannot have its seats on some date answers `409
seats_unavailable`. Each refused date in `operation.allocations` and
`handoff.allocations` says why in `code`: `seat_unavailable` (sold, or held
by another buyer) or `seat_held_for_renewal` (held for a holder's renewal).
Availability already shows seats held for a renewal as `blocked`, so a picker
never offers them. So does the date's own seat map for a buyer of that one
date (`/pub/events/:key/objects`). A hold on one, from a buyer or from your
server (`POST /v1/events/:key/hold`), answers `409 conflict` with
`code: "seat_held_for_renewal"`. Your organizer seat map
(`GET /v1/events/:key/objects`) shows each seat's physical state, so these
seats stay `free` there, and `heldForRenewal` lists them: don't sell them.
The field is there only while at least one seat of the date is held for a
renewal, so a date with none answers exactly as before.

`GET /pub/seasons/:key/availability` answers `held` for a seat that this
buyer's own session holds now: a hold that is not booked yet and has not run
out. A session that took over another one (`/session/adopt`) sees that
session's holds the same way. Every other buyer reads the same seat as
`blocked`. Once the hold is booked, released or past its deadline, its seats
read `blocked` or `free` like anyone else's.

`GET /v1/seasons/:key/holds/:operationId` returns the trusted Event, label,
object, category, optional tier, and quantity allocation. It deliberately
contains no `unitPrice`, `currency`, subtotal, or total. The response fixes
`pricingAuthority` to `"host"` and `authoritativeAmountIncluded` to `false` so
the allocation cannot be mistaken for a commercial quote. Calculate the
package amount in your own trusted system, take payment there, then book the
same operation. The booking body accepts only `bookActionId` and `bookingRef`;
commercial fields are rejected instead of silently ignored.

```http title="book"
POST /v1/seasons/sea_…/holds/sop_…/book
Authorization: Bearer sk_test_••••••••
Content-Type: application/json

{ "bookActionId": "sba_1", "bookingRef": "order_1" }
```

Booking may return `202 Accepted` with `Location` and `Retry-After`. Poll that
booking URL until `state` is terminal; replaying the same action is exact.

Cancel the booking with a new caller-stable action while repeating the original
booking and published Plan identities:

```http title="cancel"
POST /v1/seasons/sea_…/bookings/sba_1/cancel
Authorization: Bearer sk_test_••••••••
Content-Type: application/json

{
  "cancelActionId": "sca_1",
  "bookingRef": "order_1",
  "planActivationId": "spa_…",
  "rightDisposition": "preserve"
}
```

### Season Best Available

When the buyer wants "the best 2 seats for the whole season", let SeatLayer
pick. It chooses seats that are free on every date in the Plan and holds the
same labels on each date in one operation.

```http title="best available"
POST /pub/seasons/sea_…/best-available
Authorization: Bearer bss_••••••••
Content-Type: application/json

{ "operationId": "sop_7d21", "qty": 2, "categoryKey": "stalls", "requireContiguous": true }
```

This is a buyer route: it takes the `bss_…` token from the session you minted
above, not a secret key, and counts against the per-IP buyer hold budget in
[rate limits](/server-api/rate-limits/). It is not a server SDK operation.

| Field | Required | Meaning |
|---|---:|---|
| `operationId` | Yes | Your stable id for this hold, starting with `sop_`. Resending the same id and body returns the first result |
| `qty` | Yes | 1 to 10 seats. More answers `422 best_available_quantity_exceeded` |
| `categoryKey` | No | Pick from one category |
| `zoneId` | No | Pick from one zone |
| `accessibility` | No | Accessibility needs the seats must meet |
| `requireContiguous` | No | `true` to fail instead of splitting the group |

The response is `{operation, labels, items, holdId, expiresAt}`. `201` means
the hold is in place on every date; `202` means it is still being applied, so
poll the `Location` header after `Retry-After`. Then inspect and book the
operation from your server exactly as for a buyer-chosen hold. Performances
already marked past are skipped. `409 seats_unavailable` means the seats it picked were taken meanwhile, with a `code` per date as for a hold; `409 conflict` with `reason` means no set of
seats is free on every date; `409 operation_mismatch` means the same
`operationId` was sent with a different body.

Cancellation requires an explicit `preserve` or `release` future-right
disposition. There is no implicit default and no automatic refund. It may also
return `202` with the booking `Location` and `Retry-After`; the retrieved
booking includes nested per-occurrence cancellation outcomes. A mixed
nonretryable result is terminal `partial_terminal` and requires reconciliation,
not a new action or blind rollback.

After the released-baseline journey, or one journey per published Plan when
there are several, ask SeatLayer to discover the retained evidence:

```http title="verify retained rehearsal"
POST /v1/seasons/sea_…/buyer-rehearsals/validate
Authorization: Bearer sk_test_••••••••
```

The released request has no body. SeatLayer joins coherent hold, booking, and
cancellation occurrences by their retained operation identities, then requires
one active in-scope webhook subscription to have returned `2xx` for all three.
The response contains one `rehearsal` result. With more than one published
Plan, proof is required independently for every published activation, and the
result's `planActivationIds` and `activationEvidence` list each one. Node.js's
`SeasonBuyerRehearsalResult` type does not name those two fields; the other six
SDKs return them in the decoded answer. Publishing another Plan invalidates
aggregate readiness until the new Plan has its own journey.
Operators never paste `sop_…`, `sba_…`, `sca_…`, or `wh_…` values into the
dashboard. A successful result records an immutable audit checkpoint; later
checks still succeed after delivery-attempt retention pruning. `409
rehearsal_incomplete` means the SDK journey or its matching webhook delivery is
not complete yet.

### When a hold can't finish

A season hold asks every date for the same seats. Most holds answer at once.
When they don't, the answer tells you what to do:

- **`202 Accepted` with `Location` and `Retry-After`.** The hold is still being
  placed on some dates. Read the `Location` after `Retry-After` seconds until
  `state` is final. Sending the same `operationId` and body again returns the
  same hold; it never holds twice.
- **`503 season_busy` with `Retry-After: 2`.** The season had too many holds at
  once, or part of it did not answer in time. Nothing was written. Send the same
  request again after `Retry-After`. A hold (`POST /pub/seasons/:key/holds`),
  Season Best Available and the server's book (`POST
  /v1/seasons/:key/holds/:operationId/book`) can answer this.
- **A hold that ends `aborted`.** One date did not answer. The season stops
  waiting on a slow date after 5 seconds and keeps asking it. Once 45 seconds
  have passed since the hold started with a date still silent, the hold is
  aborted on every date and its seats are free again. Reading the operation
  then shows `state: "aborted"`. Hold again with a new `operationId`: the old
  one keeps its answer.

**How long a hold lasts.** `expiresAt` in the answer says when the hold ends;
book before then. A hold made with a buyer session lasts 15 minutes, whether
your server minted the session (`POST /v1/seasons/:key/buyer-access-sessions`)
or the browser did (`POST /pub/seasons/:key/sessions`), because a person is
choosing and paying: with your own checkout, inspect, take the payment and book
within those 15 minutes. A hold made with no buyer session lasts 60 seconds,
unless the season takes payment through SeatLayer's checkout (`checkoutMode:
"seatlayer"`), when it lasts 15 minutes too. The API has no call that extends a
Season hold. After
`expiresAt` its seats go back on sale and a book answers `409
hold_not_active`; hold again with a new `operationId`.

## Incumbent import and renewal offers

**POST /v1/seasons/:key/imports**. Authentication: Secret key
**GET /v1/seasons/:key/imports/:importId**. Authentication: Secret key
**POST /v1/seasons/:key/renewal-offers**. Authentication: Secret key
**GET /v1/seasons/:key/renewal-offers**. Authentication: Secret key
**GET /v1/seasons/:key/renewal-offers/:offerId**. Authentication: Secret key
**POST /v1/seasons/:key/renewal-offers/:offerId/extend**. Authentication: Secret key
**GET /v1/seasons/:key/renewal-offers/:offerId/inspect**. Authentication: Secret key
**POST /v1/seasons/:key/renewal-offers/:offerId/commit**. Authentication: Secret key
**POST /v1/seasons/:key/renewal-offers/:offerId/decline**. Authentication: Secret key
**POST /v1/seasons/:key/renewal-offers/:offerId/release**. Authentication: Secret key

Dry-run an incumbent file, then commit the same rows. `POST /imports` commits
unless you send `"dryRun": true`, so send `true` first. (This is the opposite of
[`/imports/from-season`](#bring-holders-from-last-season), which is a dry run
unless you send `false`.) Invalid or conflicting rows stay explicit and do not
create rights. Each accepted row becomes one
Contract and one reserved Seat Right, fenced on every included Event. Send at
most 100 rows a call; each holder can have up to 20 seats, each listed once, and
every id is up to 160 letters, digits and `. _ : -`. Each row is fenced on every
date, so a package of more than 20 dates takes fewer rows a call:
`floor(2300 / (dates + 3))`, which is 82 at 25 dates. A call with more answers
`422 invalid_rows` with `maxRows`, the most it takes.

A dry run checks the rows against this season's own rights. A seat sold, held or
reserved by another season since then is only found when you commit. The call
then answers `422 fence_failed` and writes nothing:

| `fence_failed` answer | What to do |
|---|---|
| `rowIds` lists rows, `retryable: false` | Those rows' seats are taken. Treat them as seat conflicts and send the rest as a new call (a new `Idempotency-Key`). |
| `rowIds` is empty, `retryable: true` | Reserving was cut short. Send the same call again with the same key. |

A row the server cannot read answers `422` with the reason (`invalid_row_id`,
`invalid_holder_ref`, `invalid_prior_plan`, `invalid_prior_contract`,
`invalid_labels`, `invalid_booking_ref`, `invalid_holder_email`,
`invalid_holder_name`) and `rowIds` naming that row, so you can fix it and send
the file again.

```http title="import"
POST /v1/seasons/sea_…/imports
Authorization: Bearer sk_test_••••••••
Idempotency-Key: 2026-incumbents
Content-Type: application/json

{
  "dryRun": false,
  "successorPlanActivationId": "spa_…",
  "rows": [
    {
      "rowId": "row_1",
      "holderRef": "holder_ada",
      "priorPlanActivationId": "spa_prior",
      "priorContractRef": "legacy_ada",
      "labels": ["A-1"],
      "existingBookingRef": "legacy_booking_ada"
    }
  ]
}
```

### Your first season on SeatLayer

When last season was sold somewhere else, import its holders from your own
records. None of the ids has to exist in SeatLayer: SeatLayer checks only their
format. `successorPlanActivationId` is the new season's published package
(`spa_…`). Each row takes these fields:

| Field | Required | What to send |
|---|---|---|
| `rowId` | Yes | Your id for the row, unique in the file, such as `row_1` |
| `holderRef` | Yes | Your id for the holder, such as a member number. The holder keeps it as their holder reference in SeatLayer. |
| `priorPlanActivationId` | Yes | Any id for last season, such as `club-season-2025-26` |
| `priorContractRef` | Yes | Your id for the holder's season ticket last season, unique within this season |
| `labels` | Yes | The holder's seats on the new floor plan, 1 to 20, such as `["A-1", "A-2"]` |
| `existingBookingRef` | No | Your id for last season's booking or order |
| `holderEmail` | No | The holder's email, up to 320 characters. Without one, SeatLayer can't email the renewal link. |
| `holderName` | No | The holder's name, up to 120 characters |

Ids are up to 160 letters, digits and `. _ : -`. A field SeatLayer doesn't know
is ignored. A seat renews at the `adult` price type unless `existingBookingRef`
names a SeatLayer season order, whose price types it keeps.

```json title="one holder from your own records"
{
  "rowId": "row_1",
  "holderRef": "member-10442",
  "priorPlanActivationId": "club-season-2025-26",
  "priorContractRef": "st-2025-10442",
  "labels": ["B-14", "B-15"],
  "holderEmail": "ana@example.com",
  "holderName": "Ana Silva"
}
```

In the dashboard, **Import current holders** on **Holders & renewals** takes the
same rows as a CSV, with these field names as its header and the seats
separated by `|`, such as `B-14|B-15`. It has a template to download, takes up
to 15,000 rows, and needs a published package.

Generate **one** time-bounded offer per prior Contract. The offer carries that
Contract's complete seat set and one immutable successor Plan activation.

```http title="generate offers"
POST /v1/seasons/sea_…/renewal-offers
Authorization: Bearer sk_test_••••••••
Idempotency-Key: 2026-offers
Content-Type: application/json

{ "successorPlanActivationId": "spa_…", "deadlineAt": 1790000000000 }
```

With **100 contracts or fewer** the offers are made in the call: `201` with
`{ "offers": [...] }`. With **more than 100**, a `renewal_run` job makes them
and the call answers `202` at once:

```json title="202 more than 100 contracts"
{
  "job": { "jobId": "sbj_rr_…", "kind": "renewal_run", "state": "planning",
           "counts": { "total": 0, "done": 0, "skipped": 0, "failed": 0 },
           "createdAt": 1789000000000, "updatedAt": 1789000000000, "completedAt": null },
  "batchId": "srb_…"
}
```

Follow it with `GET /v1/seasons/:key/jobs/:jobId` until `state` is
`completed` (see [Follow a job](#follow-a-job)), then read the offers with
`GET /renewal-offers`, page by page. The same `Idempotency-Key` answers the same
job, however often it is sent, and each holder gets one offer. When the job
ends, `season.bulk_action.completed` is sent with `kind: "renewal_run"` and
the `batchId`.

`GET /v1/seasons/:key/renewal-offers` lists every offer, newest first, 100 a
page. `nextCursor` reads the next page (`?cursor=…`) and is `null` on the last;
`limit` asks for fewer (1-100). A cursor or limit the server cannot read answers
`400 invalid_cursor` or `400 invalid_limit`. The list is complete once any
`renewal_run` job has completed: read while one is running, it may miss offers
the job is still making.

To email the holders of a batch a job made, send `POST /renewal-notices` with
`{ "batchId": "srb_…" }`: every open offer that batch made, the same offers a
`201` would have listed.

```http title="the next page of offers"
GET /v1/seasons/sea_…/renewal-offers?cursor=eyJhdCI6…
Authorization: Bearer sk_test_••••••••
```

An offer past its deadline lapses the moment it is read, and otherwise in the
season's own background pass, at most 100 offers a pass, so a deadline shared by
thousands of holders lapses over a few minutes rather than all at once. An offer
with a SeatLayer checkout payment still open lapses when that payment's window
ends.

Browser `POST /pub/seasons/:key/renewal-intents` records holder intent only. It
requires a buyer-access session bound to the offer's opaque holder reference;
an unbound or different holder is refused. It is not proof of purchase. After
you inspect the offer, commit with a stable
action id, order/booking references, and the exact Plan activation. A wrong Plan
is `409 plan_activation_mismatch`. Commit may return `202` with `Location` and
`Retry-After`; poll the offer until terminal. `commitOutcomes` retains each
Event as `pending`, `committed`, or `failed`. A mixed nonretryable result is
terminal `partial_terminal`, emits `season.operation.partial_terminal`, and
requires reconciliation rather than a new commit action or blind rollback.
Decline releases the right set immediately. It takes an optional
`{ "reason": "Moving away" }` (1–200 characters, otherwise `422
invalid_reason`), kept on the offer as `declineReason`: retrieve and list show
it. A repeated decline keeps the first reason. Release is only valid after
terminal lapse. Extension is explicit and must move the deadline forward;
there is no default extension. A lapsed offer can be reopened the same way
while its seats are still kept, that is before they are released: extend it to
a future deadline and it reads `offered` again, with the same renewal link and
its reminders moved. No webhook is sent for an extend or a reopen. Once the
seats are released, extend is `409 offer_terminal`; while a release of that
offer is running, it is `409 release_in_progress`. Account-specific organizer
bounds and permission policy still apply.

### Release every lapsed seat at once

**POST /v1/seasons/:key/renewal-offers/release-lapsed**. Authentication: Secret key

`POST /renewal-offers/:offerId/release` releases one lapsed offer.
`POST /renewal-offers/release-lapsed`, with an `Idempotency-Key` and no body,
releases every offer that has lapsed, and every offer whose deadline had passed
when you sent it, as a `lapsed_release` job: `202 { "job": … }`. Each seat goes
back on sale on every date. An offer you extend before its turn, or that its
holder renews, is skipped and keeps its seat. Follow the job with
`GET /jobs/:jobId`; `counts.done` is how many were released. When it ends,
`season.bulk_action.completed` is sent with `kind: "lapsed_release"`, and each
release sends its own `season.renewal.released`. Offers that lapse later are
released by sending it again with a new key. One release job runs at a time:
another answers `503 job_busy`; send it again shortly.

### A renewal taken by phone or at the box office

Commit needs the holder's intent: without one it is `409 intent_required`.
When the holder tells your staff they are renewing, record the intent with your
secret key, take the payment your way, then commit as above.

**POST /v1/seasons/:key/renewal-offers/:offerId/intent**. Authentication: Secret key

```http title="record the intent"
POST /v1/seasons/sea_…/renewal-offers/sro_51e0…/intent
Authorization: Bearer sk_live_••••••••
```

The answer is `{ offer }` in state `intent_received`, and you get
`season.renewal.intent_received`. A repeat answers the same offer. An offer
that was renewed, declined or lapsed is `409 offer_not_open`. The holder
keeps the offer's deadline: record the intent and commit before it.

## Renew with SeatLayer checkout

**GET /v1/seasons/:key/renewal-offers/:offerId/quote**. Authentication: Secret key
**POST /v1/seasons/:key/renewal-offers/:offerId/checkout**. Authentication: Secret key

When SeatLayer takes the payments for the season (`checkout_mode:
"seatlayer"`), your server can renew a holder with no SeatLayer page in
between: read the price, start a checkout, and send the holder to pay. With your
own checkout, inspect and commit the offer instead, as above.

```http title="quote"
GET /v1/seasons/sea_…/renewal-offers/sro_51e0…/quote
Authorization: Bearer sk_live_••••••••
```

```json title="200"
{
  "offerId": "sro_51e0…",
  "state": "offered",
  "totalMinor": 13500,
  "currency": "GBP",
  "lines": [
    { "label": "A-1", "category": "standard", "priceTypeKey": "adult", "amountMinor": 9000 },
    { "label": "A-2", "category": "standard", "priceTypeKey": "child", "amountMinor": 4500 }
  ],
  "performances": [{ "eventKey": "ev_3709…", "name": "Night 1", "startsAt": 1790000000000 }],
  "problem": null
}
```

Each line is one seat for the whole package, priced as the checkout will charge
it: the same seats, and the same price type the holder had.

A cancelled date is not renewed. `performances` lists only the dates left, and
each seat costs its package price less one date's share for every cancelled
date. A date's share is the seat's package price divided by the package's dates,
rounded down: the amount a date cancel refunds on every date but the order's
last, which also returns what is left over. A package of 19 dates at
£380 with one cancelled renews at £360. With your own checkout, charge the
quote's `totalMinor` before you commit, so a holder pays the same whichever way
they renew. `problem` is null
when SeatLayer checkout can take the renewal now. Otherwise it says why not:
`offer_not_open`, `checkout_mode_not_seatlayer`, `sales_ended`,
`plan_not_published`, `seats_changed`, `prices_missing`,
`unsupported_currency`, `gateway_not_connected` or `gateway_currency_mismatch`.

```http title="checkout"
POST /v1/seasons/sea_…/renewal-offers/sro_51e0…/checkout
Authorization: Bearer sk_live_••••••••
Idempotency-Key: renew-ana-2027
Content-Type: application/json

{ "returnUrl": "https://tickets.yourclub.example/renewed" }
```

```json title="201"
{
  "orderId": "ord_ea11…",
  "totalMinor": 13500,
  "currency": "GBP",
  "expiresAt": 1790000900000,
  "payment": { "url": "https://checkout.provider.example/…" }
}
```

Send the holder to `payment.url`. When they pay, the offer is renewed on every
date and the tickets are emailed, exactly as on the hosted renewal page. You get
`season.order.paid`, then `season.renewal.renewed`. The holder comes back to
`returnUrl` with `seatlayer_checkout=success` or `seatlayer_checkout=cancelled`
added. `returnUrl` must be on one of your allowed domains (the ones your embeds
use) or your SeatLayer website; anything else is `422 invalid_return_url`.
Tickets go to the email on file for the holder, and `buyerEmail` is used only
when there is none. `provider` picks a gateway when you have more than one.

While the payment is open, the offer is held for that order: it cannot lapse,
be declined or be committed another way. The same `Idempotency-Key` answers the
same order. A new call starts again once the provider confirms the earlier
payment was not made, and is `409 payment_in_progress` until then. A paid order
whose offer can no longer be renewed is refunded.

| Refusal | When |
|---|---|
| `404 offer_not_found` | No such offer in this season. |
| `409 offer_not_open` | The offer was renewed, declined or lapsed; `state` says which. |
| `409` with a quote `problem` | SeatLayer checkout cannot take this renewal now. |
| `409 insufficient_hosted_credits` | Not enough hosted ticket credits for every seat on every date. |
| `422 invalid_return_url` | `returnUrl` is missing or not on one of your domains. |

For one holder, use the same calls under
[`/v1/holders/:holderRef`](/server-api/holders/#renew-a-holders-seats).

## Bring holders from last season

**POST /v1/seasons/:key/imports/from-season**. Authentication: Secret key

Instead of building an import file, point at a previous season of the same
account and mode. SeatLayer takes every holder who still has a seat on at least
one date of that season and runs them through the same checks as
`POST /imports`. Test bookings, refunded or cancelled orders, holders with more
seats than one right can hold, and holders without a usable reference are left
out and counted in `excluded`.

`dryRun` is `true` unless you send `false`. Look at the dry run first, then send
the same body with `"dryRun": false` and a new `Idempotency-Key`.

```http title="dry run"
POST /v1/seasons/sea_2027…/imports/from-season
Authorization: Bearer sk_live_••••••••
Idempotency-Key: bring-2026-holders-check
Content-Type: application/json

{ "sourceSeasonId": "sea_2026…", "successorPlanActivationId": "spa_…", "dryRun": true }
```

```json title="200 dry run"
{
  "import": {
    "sourceSeasonId": "sea_2026…",
    "successorPlanActivationId": "spa_…",
    "dryRun": true,
    "holders": 3,
    "acceptedCount": 2,
    "alreadyImported": 0,
    "rejectedCount": 1,
    "withEmail": 1,
    "hosted": 1,
    "integrator": 2,
    "excluded": { "refunded": 1, "rehearsal": 1, "tooManySeats": 0, "unusableRef": 0 },
    "importIds": ["sim_…"],
    "rejected": [{ "holderRef": "booking_pia_2026", "labels": ["B-4"], "errorCode": "unknown_seat" }],
    "preview": [
      { "holderRef": "ord_…", "holderName": "Hanna Holder", "hasEmail": true, "labels": ["A-2", "A-3"] },
      { "holderRef": "crm-ann", "holderName": "Ann Lee", "hasEmail": true, "labels": ["A-1"] }
    ]
  }
}
```

The commit answers `201` with the same shape for **100 holders or fewer**. With
**more than 100**, a `holder_import` job brings them across and the commit
answers `202 { "job": … }`. Follow it with `GET /v1/seasons/:key/jobs/:jobId`:
when it completes, its `summary` has the same counts (`holders`,
`acceptedCount`, `alreadyImported`, `rejectedCount`, `withEmail`, `hosted`,
`integrator`, `excluded`) and up to 200 `rejected` holders as `{ holderRef,
errorCode }`. The holders are fixed when the job starts, and the same
`Idempotency-Key` answers the same job. One bring-across runs at a time:
another answers `503 job_busy`. A source season can bring up to 20,000
holders.

A holder is refused with
`unknown_seat` when a seat is not on the new plan and `seat_conflict` when
someone else already holds it. Running it again is safe: a holder already
brought across counts under `alreadyImported`, never twice.

Each holder keeps the `holderRef` they had last season, so their seasons and
their customer carry on: the reference you imported or renewed them under, or the `buyerRef` of the buyer session your system sold them
through. A SeatLayer checkout sale with no reference of its own is known by its
order id, and anything else by its `bookingRef`. Holders who bought through
SeatLayer checkout come with the name and email of their order. Holders your
own system booked come with the email and name you gave them
(`PATCH /v1/holders/:holderRef`), else the ones last season's import gave them; with none, SeatLayer cannot email their renewal
link. Read each import with `GET /v1/seasons/:key/imports/:importId`, using the
ids in `importIds`.

| Error | Meaning |
|---|---|
| `404 source_season_not_found` | No season with that key in this account and mode |
| `409 source_too_large` | More than 20,000 holders to bring across |
| `503 job_busy` · `503 season_not_configured` | Another bring-across is running, or the season is not ready: send it again shortly |
| `409 season_not_active` · `409 plan_not_published` | Activate this season and publish the package first |
| `422 invalid_source_season` · `422 invalid_successor_plan` | A key is missing, or the source is this season |

## Return or reclaim one occurrence

> **In every server SDK from 0.9.0**
>
> These two secret-key operations are in all seven server SDKs from `0.9.0`:
> `returnSeasonOccurrenceInventory` and `reclaimSeasonOccurrenceInventory` in
> Node.js, for example. `0.8.0` does not have them: on `0.8.0`, or from any
> other language, call the REST routes directly.

Return the exact labels from one active booked Season allocation to ordinary
Event inventory without cancelling the holder's complete Season contract:

```http title="return one occurrence"
POST /v1/seasons/sea_…/occurrences/ev_night_2/returns
Authorization: Bearer sk_test_••••••••
Content-Type: application/json

{
  "actionId": "sor_order_1_night_2",
  "bookingRef": "order_1",
  "planActivationId": "spa_…",
  "labels": ["A-1"],
  "source": { "bookingActionId": "sba_1" }
}
```

For a renewed right, use `{ "renewalOfferId": "sro_…" }` as `source` instead.
SeatLayer resolves the allocation for you; callers never send a child hold, internal allocation, or Seat Right ID. `actionId` owns
exact replay. Reusing it with any changed Event, Plan, source, booking reference,
or label set returns `409 occurrence_action_mismatch`.

A successful return emits `season.occurrence.returned` and makes only that
Event's labels available for ordinary sale. Reclaim succeeds only while the
same return remains active and every label is still free, unheld, unbooked, and
unclaimed by another Season allocation:

Pass the return's `occurrenceInventoryAction.returnActionId` as
`returnActionId`:

```http title="reclaim the same occurrence"
POST /v1/seasons/sea_…/occurrences/ev_night_2/reclaims
Authorization: Bearer sk_test_••••••••
Content-Type: application/json

{
  "actionId": "src_order_1_night_2",
  "returnActionId": "sor_order_1_night_2",
  "bookingRef": "order_1",
  "planActivationId": "spa_…",
  "labels": ["A-1"],
  "source": { "bookingActionId": "sba_1" }
}
```

Reclaim emits `season.occurrence.reclaimed`. A `preserve` cancellation is refused
while that booking has an active occurrence return; a full `release` cancellation
does not seize independently held or resold Event inventory. Neither operation
prices a resale, moves money, refunds a buyer, creates a listing, or issues a
ticket. Those commerce decisions remain entirely in the host platform.

## Holders, orders, renewal emails, and reports

These are the dashboard's Holders and Reports tabs for your own server. Each
call does the same work as the matching dashboard button. The order calls act
on orders SeatLayer took: SeatLayer checkout and the box office. A season sold
through your own checkout has no SeatLayer orders; your system refunds those.

- All seven server SDKs have these calls from `0.9.0`, for example
  `listSeasonHolders` and `refundSeasonOrder` in Node.js. `0.8.0` does not, so
  on `0.8.0` call the routes over HTTP.
- Use a secret key (`sk_live_…` or `sk_test_…`). It reaches the seasons of its
  own account and mode. Another account's season, or a live season from a test
  key, is `404 not_found`.
- A publishable key gets `403 publishable_key_not_allowed`. A dashboard login
  cookie gets `401`.
- These calls share the 600-a-minute budget of the Season setup and operations
  routes.
- Each answer carries only the fields shown here. Internal ids, the payment
  provider's refund id, and staff notes are never in them. A package is named
  by its plan key (`spl_…`), the `plans[].key` of `GET /v1/seasons/:key`.

### List holders

**GET /v1/seasons/:key/holders**. Authentication: Secret key

Everyone who holds this season: SeatLayer checkout and box office buyers
(`hosted`), bookings your system made (`integrator`), and holders brought over
from last season (`imported`).

| Query | Meaning |
|---|---|
| `q` | Search name, email, reference, order number, or seat. An imported holder is found by the name and email the import gave. |
| `status` | `active`, `cancelled`, or `renewal` |
| `limit` | 1–100, default 50 |
| `cursor` | `nextCursor` from the page before |

```json title="200"
{
  "holders": [
    {
      "id": "hld_6c0edf602c0a948627fec31675ee011e",
      "kind": "hosted",
      "bookingRef": "ord_ea11…",
      "orderId": "ord_ea11…",
      "orderNumber": "#1098 5206",
      "holderName": "Hanna Holder",
      "holderEmail": "hanna@example.com",
      "holderRef": null,
      "labels": ["A-2", "A-3"],
      "packageName": "Full season",
      "packageId": "spl_97d1…",
      "dates": [
        { "eventKey": "ev_3709…", "state": "active" },
        { "eventKey": "ev_1eff…", "state": "active" },
        { "eventKey": "ev_80b7…", "state": "active" }
      ],
      "datesTotal": 3,
      "datesActive": 3,
      "datesCancelled": 0,
      "paid": { "amountMinor": 18000, "currency": "GBP", "refundedMinor": 0 },
      "soldAtCounter": false,
      "orderStatus": "confirmed",
      "status": "active",
      "renewal": null,
      "boughtAt": 1790220682247
    }
  ],
  "nextCursor": "eyJwIjoiYiIs…",
  "totals": { "holders": 3, "active": 2, "cancelled": 0, "imported": 1 }
}
```

`totals` comes with the first page only. A page can hold fewer rows than
`limit` and still have a `nextCursor`; keep reading until it is `null`. `id` is
stable but opaque: use `orderId`, `bookingRef`, or `holderRef` to match your
records. `status` is one of `active`, `partly_cancelled`, `cancelled`,
`needs_review`, `reserved`, `renewal_open`, `renewed`, `declined`, and
`lapsed`. An imported holder whose seats are held but who has no renewal offer
yet is `reserved`, the word their own seasons use; once an offer is open they
are `renewal_open`. An
imported holder shows the `holderName` and `holderEmail` the import gave (or
you set later for their renewal). A date reads `cancelled` once every seat of
it has been given back, by the holder or by you. A date you
[cancelled](#postpone-move-or-cancel-a-date) reads `date_cancelled`, and a
date you postponed reads `postponed`, with `newStartsAt` once it moves (`null`
until then). `datesActive` counts `active` and `postponed` dates;
`datesCancelled` counts `cancelled` and `date_cancelled` dates, and `status`
follows them. The `status` filter and `totals` go by seats still booked, so a
holder whose dates you cancelled stays under `active` there.

### Refund an order

**POST /v1/seasons/:key/orders/:orderId/refund**. Authentication: Secret key

Pays money back through the payment provider that took it. Leave out
`amountMinor` to refund what is left; a full refund also cancels every date,
so the seats go back on sale and the tickets stop working. A partial refund
keeps the seats and tickets.

```http title="refund part of an order"
POST /v1/seasons/sea_a245…/orders/ord_2596…/refund
Authorization: Bearer sk_live_••••••••
Idempotency-Key: refund-ord_2596-1
Content-Type: application/json

{ "amountMinor": 5000 }
```

```json title="200"
{
  "orderId": "ord_2596…",
  "refundId": "rfo_1979…",
  "amountMinor": 5000,
  "currency": "GBP",
  "state": "succeeded"
}
```

`Idempotency-Key` is required: without it the call is `400
idempotency_key_required` and nothing moves. `refundId` is SeatLayer's refund
(`rfo_…`), built from your account and the key. Send the same key again and
you get the same answer; the dashboard sending that key reaches the same
refund. A `202` with `"state": "pending"` means the provider has not confirmed
yet: retry with the same key to read it.

| Error | Meaning |
|---|---|
| `409 not_refundable` | A box office sale (`code: box_office_sale`) or an order with no payment to reverse |
| `409 already_refunded` · `409 refund_failed` · `409 gateway_not_connected` | Nothing left, the provider said no (`detail` says why), or payments are disconnected |
| `422 invalid_amount` | Not a whole number above zero, or more than `outstanding` |
| `502 refund_recovery_required` | The provider may have taken it; retry with the same key |

### Cancel an order without a refund

**POST /v1/seasons/:key/orders/:orderId/cancel**. Authentication: Secret key

For money handled outside SeatLayer: a lost payment dispute, or a refund made
another way. Every ticket stops working and every date goes back on sale.
`Idempotency-Key` is required.

```http title="cancel"
POST /v1/seasons/sea_a245…/orders/ord_ea11…/cancel
Authorization: Bearer sk_live_••••••••
Idempotency-Key: cancel-ord_ea11
Content-Type: application/json

{ "reason": "refunded_elsewhere", "refundConfirmed": true, "notifyBuyer": false }
```

```json title="200"
{
  "receipt": {
    "orderId": "ord_ea11…",
    "displayRef": "#1098 5206",
    "status": "refunded",
    "currency": "GBP",
    "settledOutsideMinor": 18000,
    "released": ["A-2", "A-3"],
    "seatsReleased": true,
    "emailQueued": false,
    "cancelledAt": 1790220682345
  }
}
```

`reason` is `lost_dispute`, `refunded_elsewhere`, or `other`; `note` is kept
for your team and never returned. Send `usedTicketsAcknowledged: true` when a
ticket was already scanned. A box office order is `409
box_office_order_use_dashboard`: staff cancel it at the counter after giving
the money back.

### Cancel one date

**POST /v1/seasons/:key/orders/:orderId/dates/:eventKey/cancel**. Authentication: Secret key

Takes back one date of an order. That date's tickets stop working first, then
its seats go back on sale; every other date stays. No money moves: refund the
date separately if you need to. `Idempotency-Key` is required; the body is
optional.

```http title="cancel one date"
POST /v1/seasons/sea_a245…/orders/ord_ea11…/dates/ev_3709…/cancel
Authorization: Bearer sk_live_••••••••
Idempotency-Key: cancel-ord_ea11-night-1
```

```json title="200"
{
  "dateCancel": {
    "eventKey": "ev_3709…",
    "ticketsVoided": 2,
    "labels": ["A-2", "A-3"],
    "state": "returned"
  }
}
```

A `202` with `"state": "pending"` means the tickets are void and the seats are
on their way back; retry with the same key. `409 date_already_used` means
someone was admitted with a ticket for that date. `409 date_not_held` or `409
conflict` means the date was already taken back. `409 performance_cancelled`
means the whole date was cancelled: refund it with the date's refund job
instead.

### Email the tickets again

**POST /v1/seasons/:key/orders/:orderId/resend**. Authentication: Secret key

Sends the season confirmation with every live ticket. Pass `email` to send it
to a new address, which also replaces the one on the order.

```json title="200"
{ "sentTo": "hanna@example.com" }
```

One order can be resent 3 times an hour (`429 rate_limited`). `409 no_tickets`
means the order has no live tickets, and `409 no_buyer_email` means a walk-up
buyer gave no address: send one in `email`.

### Renewal links and emails

**GET /v1/seasons/:key/renewal-hosted**. Authentication: Secret key
**POST /v1/seasons/:key/renewal-offers/:offerId/link**. Authentication: Secret key
**POST /v1/seasons/:key/renewal-offers/:offerId/contact**. Authentication: Secret key
**POST /v1/seasons/:key/renewal-notices**. Authentication: Secret key
**POST /v1/seasons/:key/renewal-offers/:offerId/resend**. Authentication: Secret key

With SeatLayer checkout, holders renew and pay on a SeatLayer page, from a
link SeatLayer emails them. `GET /renewal-hosted` shows where each offer
stands and whether payments can be taken, 500 offers a page, newest first:
`nextCursor` reads the next page (`?cursor=…`, `null` on the last) and `limit`
asks for fewer (1-500):

```json title="200"
{
  "checkoutMode": "seatlayer",
  "readiness": { "ready": true, "problem": null },
  "holdersWithoutEmail": 1,
  "offers": [
    {
      "offerId": "sro_be78…",
      "holderName": "Ana Silva",
      "holderEmail": "ana@example.com",
      "linkActiveSince": null,
      "paymentActive": false,
      "notices": {
        "invitedAt": null,
        "lastReminderAt": null,
        "nextNoticeAt": null,
        "nextNoticeKind": null,
        "problem": null
      }
    }
  ],
  "nextCursor": null
}
```

`readiness.problem` is `own_checkout`, `prices_missing`, or a payments problem
when holders cannot pay yet. A renewal keeps the price type each seat was sold
as, so a child holder renews as a child: when a package they renew into prices
no child seat, `prices_missing` comes with `missingPrices`, each
`{ packageId, categoryKey, priceTypeKey }`, and those holders' renewals are
refused until you price it. They are never charged the adult price instead.

- `POST /renewal-offers/:offerId/link` answers `201` with `{ "url": "…/r/…" }`.
  The link is shown once, and making a new one turns the previous link off, so
  do not retry this call blindly: each call makes another link.
- `POST /renewal-offers/:offerId/contact` with `{ "email", "name" }` answers
  `{ "contact": { "name": "Ana Silva", "email": "ana@example.com" } }`. A new
  email turns the current link off.
- `POST /renewal-notices` emails the invitation now, then reminders 7 days and
  1 day before the deadline. Send `{ "offerIds": […] }` to pick holders (up to
  20,000; more is refused `422 too_many_offer_ids`, never cut short), or no
  body for every open offer. It answers `{ "scheduled": 2, "withoutEmail": 1 }`.
  A holder is emailed each notice once, even if the email is delivered to
  SeatLayer's mail queue twice.
- `POST /renewal-offers/:offerId/resend` sends one holder a new invitation and
  answers `202` with `{ "ok": true }`. The old link stops working. A holder
  with no email is `422 holder_email_missing`.

Emails need SeatLayer checkout: on your own checkout, notices and resend are
`409 checkout_mode_not_seatlayer`, and your system tells holders.

### Reports and downloads

**GET /v1/seasons/:key/reports/sales**. Authentication: Secret key
**GET /v1/seasons/:key/reports/seats**. Authentication: Secret key
**GET /v1/seasons/:key/reports/holders.csv**. Authentication: Secret key
**GET /v1/seasons/:key/reports/orders.csv**. Authentication: Secret key
**GET /v1/seasons/:key/seat-counts**. Authentication: Secret key

`GET /reports/sales` is the Reports tab in figures: money per package, channel
(`online` or `box_office`) and currency, seats per package and per date,
holders, and renewals. It holds totals only, never a buyer.

```json title="200 (trimmed)"
{
  "report": {
    "season": { "key": "sea_a245…", "name": "Holders", "currency": "GBP", "mode": "live", "checkoutMode": "seatlayer", "timezone": null },
    "generatedAt": 1790220682369,
    "ownCheckout": false,
    "money": {
      "rows": [
        {
          "packageId": "spl_97d1…", "packageName": "Full season", "channel": "online", "currency": "GBP",
          "orders": 1, "refundedOrders": 0, "seats": 2,
          "grossMinor": 18000, "discountMinor": 0, "refundedMinor": 0, "netMinor": 18000
        }
      ]
    },
    "seats": { "sold": 3, "byPackage": [{ "packageId": "spl_97d1…", "packageName": "Full season", "seats": 3, "holders": 2 }], "byDate": [] },
    "holders": {
      "total": 3, "active": 2, "cancelled": 0, "imported": 1, "importedRenewed": 0,
      "soldThroughSeatLayer": 1, "soldThroughYourCheckout": 1,
      "byStatus": { "all": 3, "active": 2, "cancelled": 0, "renewal": 1 }
    },
    "renewals": { "offered": 0, "renewed": 0, "declined": 0, "lapsed": 0, "open": 0, "needsReview": 0, "rate": null },
    "downloadLimit": 50000,
    "unavailable": []
  }
}
```

A section that could not be read right now is `null` and named in
`unavailable`; it is never a wrong zero. `GET /seat-counts` returns the same
`seats` block on its own, and `null` when it cannot be read.

`GET /reports/seats` counts free seats, per package on every one of its dates
still to come, and per date:

```json title="200"
{
  "seats": {
    "packages": [
      {
        "packageId": "spl_97d1…", "packageName": "Full season", "datesLeft": 3, "state": "ok",
        "freeEveryDate": 7, "notEveryDate": 0, "renewalHeld": 1
      }
    ],
    "dates": [{ "eventKey": "ev_3709…", "free": 8 }]
  }
}
```

The two downloads answer `text/csv`, the same files as the dashboard. Every
server SDK has them from `0.9.0` and returns the CSV text unparsed, for example
`exportSeasonHoldersCsv` and `exportSeasonOrdersCsv` in Node.js.

- `holders.csv` has 17 columns: Name, Email, Reference, Your reference, Seats,
  Package, Dates active, Paid, Refunded, Currency, Method, Sold through, Order
  status, Holder status, Renewal state, Renewal deadline, Bought. It takes the
  same `q` and `status` as the holder list. Past 50,000 holders it is `413
  download_too_large`: filter by status.
- `orders.csv` has every order SeatLayer took for the season. A season on your
  own checkout has none: `409 season_sold_elsewhere`.

### Webhooks for these calls

| Call | Webhook |
|---|---|
| A SeatLayer checkout or box office sale is paid | `season.order.paid` |
| Refund (full or partial) | `season.order.refunded`; a full refund also sends `season.booking.cancelled` |
| Cancel an order without a refund | `season.booking.cancelled` |
| Cancel one date | `season.occurrence.returned` |
| Postpone, move or cancel a date for everyone | `season.performance.postponed`, `season.performance.rescheduled`, `season.performance.cancelled` |
| A refund job, or the job voiding its tickets, for a cancelled date ends | `season.bulk_action.completed` |
| A job making offers, releasing lapsed seats or bringing holders across ends | `season.bulk_action.completed`, with its `kind` and `done`, `skipped` and `failed` |
| A full refund, a date given back or a date removed voids tickets | `season.ticket.voided` for each ticket, once; if sending fails, SeatLayer sends it again later |

There is no webhook for a ticket resend, a renewal email being sent, a date
change's emails, or a contact change. See [Webhook events](/webhooks/events/#season-orders) for the
payloads.

## Postpone, move or cancel a date

**POST /v1/seasons/:key/amendments**. Authentication: Secret key
**POST /v1/seasons/:key/performances/:eventKey/refunds**. Authentication: Secret key
**GET /v1/seasons/:key/jobs**. Authentication: Secret key
**GET /v1/seasons/:key/jobs/:jobId**. Authentication: Secret key

Three amendment kinds change one date of a published Season. Each keeps every
holder's seat and sends its own webhook. Each applies at once: an amendment has
no dry run, so a body with `dryRun` or `previewHash` is `422
dry_run_not_supported` and nothing changes.

| `kind` | What happens | Webhook |
|---|---|---|
| `postpone` | The date has no new time yet. It stays in the package and tickets stay valid. | `season.performance.postponed` |
| `reschedule` with `startsAt` | The date moves. Tickets stay valid for the new time. | `season.performance.rescheduled` |
| `cancel` | The date will not happen. It leaves sale and holds, like a date that has taken place, and every ticket for it stops working. | `season.performance.cancelled` |

A cancelled date reads `cancelled: true` in `GET /v1/seasons/:key/performances`
and in the buyer's season read (`GET /pub/seasons/:key`), so a page can say
"Cancelled" rather than "Taken place". It also reads `past: true`, as before,
so a page that knows only `past` still leaves it out. The season keeps selling
the dates left at the full package price; a renewal charges only the dates left
(see the renewal quote).

```http title="cancel a date and refund it"
POST /v1/seasons/sea_…/amendments
Authorization: Bearer sk_live_••••••••
Idempotency-Key: night-3-storm
Content-Type: application/json

{ "eventKey": "ev_night_3", "kind": "cancel", "refund": "per_date", "reason": "Storm" }
```

```json title="201"
{
  "amendment": { "amendmentId": "sam_…", "kind": "cancel", "state": "applied", "…": "…" },
  "refundJob": {
    "jobId": "sbj_refund_sam_…",
    "kind": "bulk_refund",
    "state": "planning",
    "counts": { "total": 0, "done": 0, "skipped": 0, "failed": 0 }
  }
}
```

`refund` works only with `cancel`; on any other kind it is `422
invalid_refund`:

- `none`, the default, refunds nothing. You can refund the date later.
- `per_date` refunds the date's share of each order, once: for each seat of
  the order still on that date, its package price divided by the dates the
  order holds, in whole cents, with the order's last date also taking what is
  left over, so the dates add up to exactly what the seat cost; never more than
  is left on the order. A
  date added to the package after the sale counts while it stays in the
  package; one removed again does not. A seat given back or taken back before
  the cancel has no share. An order with no seat left on the date is skipped.

A date refund is always that date's share. To refund a whole order, use
[Refund an order](#refund-an-order), which also cancels its dates and frees its
seats. `refund: "full"` is `422 date_refund_per_date_only`.

Refunding moves money, so it needs the `event:refund` permission: a dashboard
designer gets `403 missing_manage_capability`; a secret key and an admin can.
Only orders SeatLayer took payment for are refunded. Box office, free and
imported holders are skipped. Read the job with `GET /v1/seasons/:key/jobs/:jobId`:
`counts.refunded` is money that went back, `counts.processing` is accepted and
not yet confirmed, and `counts.failed` provably moved nothing. `counts.uncertain`
is a refund the gateway never answered: the money may have gone, so don't refund
it another way. SeatLayer keeps asking the gateway, and the counts follow.
A refund on a Season sold through your own
checkout (`checkout_mode` other than `seatlayer`) is `409
checkout_mode_not_seatlayer`.

Cancelling a date voids every live ticket for it, season tickets and single
tickets alike, so the door refuses them online and on its offline list (whose
version moves). It runs as a job named `sbj_void_` and the cancel's
`amendmentId`, one order per item (see [Follow a job](#follow-a-job)), and
starts with the cancel: a retried or repeated cancel joins the same job, which
voids each ticket once. Each season ticket voided is told by
`season.ticket.voided` with reason `date_cancelled`. A ticket already given
back keeps its own `returned` webhook, and a ticket already scanned stays
checked in, as the record of entry. Single tickets for the date are voided
too, with no webhook of their own. Voiding is the same whether you refund or
not: `per_date`, at once or later, still pays each seat that was live when the
date was cancelled.

No ticket for a cancelled date is valid afterwards either. A ticket issued on
it later, for example by a payment that was still going through at the
cancel, is written void, and the box office refuses the date (`409
performance_cancelled`). The job starts even if the cancel's answer is lost
before it does: the season starts it itself within a minute, and a retry still
joins it.

The cancel also ends the date's own sales, for good. A date selling single
tickets stops: a new hold is refused, and a seat held before the cancel can no
longer go to checkout (`409 event_closed`), so nothing is charged. Turning
single tickets on again, or opening the season's sales, never reopens a
cancelled date, and neither does anything else: moving its sales to
`testable` or `live` by hand (`POST /v1/events/{key}/sales/transition`), or a
run's "sales on" for all its dates, is refused with `409
season_date_cancelled`. That holds for a date that never sold too.

A cancelled date is cancelled once. Cancelling it again answers the first
cancel, with the same `amendmentId`, and sends no second webhook; with a
`refund`, it starts the date's refund job if none has run. Once a date is
cancelled:

- a hold that includes it can no longer be booked (`409
  performance_cancelled`); an order already paid through SeatLayer checkout
  for such a hold is refunded in full;
- a holder's give-back and your "cancel one date" on it are refused (`409
  performance_cancelled`): its money goes back through its refund job;
- it can't be moved (`reschedule`), postponed or replaced, nor marked as
  taken place: `409 performance_cancelled`.

A date in two seasons is cancelled for both: the cancel voids every ticket on
it, so the other season's packages no longer include it either.

If the cancel is saved but its refund job does not start, the answer is `503
refund_not_started` with `retryable: true` and the `amendment`. Nothing is
kept under the `Idempotency-Key`, so send the same request again.

### Email the date's customers

Add `"notifyCustomers": true` to a `postpone`, a `reschedule` that moves the
date, or a `cancel`, and SeatLayer emails everyone with a SeatLayer ticket for
the date: this season's holders, holders of other seasons that share the date,
and single-ticket buyers. Each order gets one email, from the club's name.

```http title="postpone a date and email its customers"
POST /v1/seasons/sea_…/amendments
Authorization: Bearer sk_live_••••••••
Idempotency-Key: night-3-postponed
Content-Type: application/json

{ "eventKey": "ev_night_3", "kind": "postpone", "notifyCustomers": true }
```

```json title="201"
{
  "amendment": { "amendmentId": "sam_…", "kind": "postpone", "state": "applied", "…": "…" },
  "customersNotified": true
}
```

- **Off by default**, with one exception: a `reschedule` of a date whose
  `postpone` was emailed is emailed too, because that email said a new date
  would follow. Send `"notifyCustomers": false` to stop it.
- **The first request decides.** `customersNotified` says whether the change's
  customers were, or are being, emailed. Repeating the change with another
  `notifyCustomers` changes nothing. A value other than `true` or `false` is
  `422 invalid_notify_customers`.
- **Only changes customers need to hear about.** A `reschedule` that only
  renames the date, a `replace` and a `cancel_exception` email nobody, and
  answer `"customersNotified": false`.
- **When.** A postpone or a move is emailed at once. A cancel is emailed once
  its tickets have stopped working (its `date_cancel_void` job). An added or
  removed date is emailed once its job has ended.
- **Who is not emailed.** An order sold through your own checkout: your system
  hears through the `season.performance.*` webhooks, so tell those customers
  from there. Also an order with no email address (a box office sale to a
  walk-up buyer), an order whose mode (test or live) is not the season's, and
  an order whose ticket for the date the change did not change.
- **What it says.** What changed, the buyer's seats on an added date, and a
  link to their tickets. It is written in the date's language, else the
  club's: English, Spanish, German, French, Hindi, Arabic, Chinese or Japanese,
  and English for any other. Replies go to the club's reply-to address, else
  to its first admin. In test mode the subject starts `[TEST] `.

**A cancel and its refund.** With `"refund": "per_date"`, a buyer the cancel's
refund job has refunded is told the refund is on its way; the refund's own
email confirms the amount. The email waits up to ten minutes for the refund
job to reach the order. A buyer who paid and gets no refund from it is asked to
reply to the club about one, when the email has someone to reply to. That
includes a single-ticket buyer and a holder of another season on the date,
whom a season's refund job never refunds. With `"refund": "none"`, the
season's own holders are told nothing about money.

**Pace.** The emails are paced so that one date never uses up the day's email
allowance. A large date's emails can take hours, and several thousand
customers take days. A cancelled or postponed date's emails go first.
Tickets, receipts and refund emails never wait behind them.

**Follow the emails** as a job: `sbj_notice_` and the change's `amendmentId`
(for an added or removed date, the `jobId` of its change). `GET
/v1/seasons/:key/jobs` lists it with kind `season_date_notice`. Its `counts`
say how far it is. When it completes, `summary` has `sent`, `failed` and
`skipped`, counted by reason, such as `external` (your own checkout),
`no_email`, `other_mode` and `no_ticket_change`. Each order is emailed at most once, however
often the job runs. The job sends no `season.bulk_action.completed`.

### Refund a cancelled date later

`POST /v1/seasons/:key/performances/:eventKey/refunds` takes `{ "amount":
"per_date", "reason"? }` and answers `202 { job }`. A date that is not
cancelled is `409 performance_not_cancelled`. `"amount": "full"` is `422
date_refund_per_date_only` (a whole order is refunded on its own), and any
other `amount` is `422 invalid_amount`. `Idempotency-Key` is optional and replays the same job; the
same key with another amount or reason is `409 job_mismatch`. While another
job holds the season the answer is `503 job_busy`, kept under no key: send it
again.

Each order is refunded once per cancelled date. The refund of one order for
one date has one fixed operation: a retried item, a second job for the date, a
second cancel, or a crash after the payment provider answered pays nothing
more. The amount the first try worked out is the amount.

A date refund pays for that date only. It never cancels the holder's season,
never frees their seats, and never voids their tickets for the other dates,
even when it is all that was left of the order. Each order sends
`season.order.refunded`; no `season.booking.cancelled` is sent.

An order that cannot be refunded yet is tried again with backoff, not
failed: its payment gateway is disconnected, the order is being edited, or
another refund of it is still settling. One the provider refuses for good is
`failed`, with its reason in `failedItems`.

### Follow a job

`GET /v1/seasons/:key/jobs` lists the Season's bulk jobs, newest first (100 at
most). `GET /v1/seasons/:key/jobs/:jobId` returns one job, its `counts`, and up
to 500 `failedItems` (for a refund, `key` is the order id and `error` the
provider's reason), with `summary`, what it ended with. A job is `planning`,
`running`, `completed`, `failed` or `cancelled`. When a job ends,
`season.bulk_action.completed` sends its counts.

| `kind` | Started by | `summary` when it completes |
|---|---|---|
| `bulk_refund` | Refunding a cancelled date | `done`, `failed`, `skipped` |
| `date_cancel_void` | Cancelling a date (its tickets stop working) | `done`, `failed`, `skipped` (orders), and `sales`: how the date's own sales ended (`done` once they have, `failed` if they could not) |
| `season_date_notice` | A date change with `notifyCustomers` ([Email the date's customers](#email-the-dates-customers)) | `sent`, `failed`, and `skipped` counted by reason |
| `renewal_run` | Generating offers for more than 100 contracts | `batchId`, `offered`, `skipped`, `failed` |
| `lapsed_release` | `POST /renewal-offers/release-lapsed` | `released`, `skipped`, `failed` |
| `holder_import` | Bringing more than 100 holders from last season | The bring-across counts and up to 200 `rejected` holders |
| `season_block_set_aside` | [Setting season seats aside](#season-seats) | Empty. Read the block with `GET /block` |
| `season_block_release` | [Releasing season seats](#season-seats) | The release's `scope`, `eventKeys`, `at` and `reason` |

The two season seats jobs are read by id only. `GET /jobs` doesn't list them,
and `season.bulk_action.completed` isn't sent for them. A `season_date_notice`
job is listed, but sends no `season.bulk_action.completed` either.

```json title="GET /v1/seasons/sea_…/jobs/sbj_refund_sam_…"
{
  "job": {
    "jobId": "sbj_refund_sam_…",
    "kind": "bulk_refund",
    "state": "completed",
    "counts": { "total": 1000, "done": 998, "skipped": 0, "failed": 2 },
    "createdAt": 1790000000000,
    "updatedAt": 1790000060000,
    "completedAt": 1790000060000,
    "failedItems": [{ "key": "ord_…", "error": "card_expired", "attempts": 1 }]
  }
}
```

Refund a failed order yourself with
[Refund an order](#refund-an-order).

## Season seats

**POST /v1/seasons/:key/block**. Authentication: Secret key
**GET /v1/seasons/:key/block**. Authentication: Secret key
**POST /v1/seasons/:key/block/release**. Authentication: Secret key

Season seats are set aside on every date before season sales open. Then a season
buyer's hold doesn't have to ask each date, and single-ticket buyers see those
seats as unavailable. Every seat your packages price is a season seat, except
the sections, categories or seats you keep for single tickets. A seat that
isn't free on every date (already sold as a single ticket, for example) stays
a single ticket. A partner's seat on a date (one a sales channel sells there)
stays out too, and no season path sells it. Both are listed in
`notFreeOnEveryDate`, a partner's seat with reason `channel`. Season seats must
be turned on for the season first (below); otherwise each write answers
`409 season_block_not_enabled`.

All seven server SDKs have these three calls from `0.9.0`:

| SDK | Set aside · read · release |
|---|---|
| Node.js, PHP, Java | `setAsideSeasonBlock` · `retrieveSeasonBlock` · `releaseSeasonBlock` |
| Python, Ruby | `set_aside_season_block` · `retrieve_season_block` · `release_season_block` |
| Go | `Seasons.SetAsideBlock` · `RetrieveBlock` · `ReleaseBlock` |
| .NET | `SetAsideSeasonBlockAsync` · `RetrieveSeasonBlockAsync` · `ReleaseSeasonBlockAsync` |

**Turn them on.** Season seats are off for every season until you turn them on
with `inventoryMode: "block"` on `createSeason` or `updateSeason`. Every season
answer reads `inventoryMode`: `block` once they are on or the season sells from
its block, `per_hold` otherwise. Turning them on changes no seat and keeps the
season's `revision`. Send `inventoryMode: "per_hold"` to turn them off again,
until seats are set aside. Before you turn them on, check what block mode
doesn't do yet (at the end of this section).

```json title="PATCH /v1/seasons/sea_…"
{ "expectedRevision": 7, "inventoryMode": "block" }
```

| Code | When |
|---|---|
| `409 season_block_packages` | The season has more than one package: season seats sell one package |
| `409 season_block_on_sale` | The season's sales have already opened, so it keeps selling on its dates |
| `409 season_not_draft_or_active` | The season is closed or archived |
| `409 season_block_exists` | `per_hold` once seats are set aside, or once the season sells from its block |
| `422 invalid_inventory_mode` | Anything but `block` or `per_hold` |

Nothing changes when one is refused, including any other field sent in the same
`updateSeason`. Setting seats aside checks the package count again, so a
package added after you turn season seats on is refused before any seat is set
aside. With season seats on, `openSeasonSales` answers
`409 block_not_ready` until the season sells from its block.

**Set them aside.** Send the season's `revision` as `expectedRevision`, and
optionally `keepForSingleTickets`. The answer is `202` with a job to follow at
`Location` (see [Follow a job](#follow-a-job)), and the block as it is now:

```json title="POST /v1/seasons/sea_…/block"
{ "expectedRevision": 7, "keepForSingleTickets": { "sectionIds": ["sec_family"] } }
```

```json title="202"
{
  "job": { "jobId": "sbsa_sbp_spl_…", "kind": "season_block_set_aside", "state": "running", "counts": { "total": 25, "done": 4, "skipped": 0, "failed": 0 }, "createdAt": 1790000000000, "updatedAt": 1790000001000, "completedAt": null },
  "block": { "mode": "per_hold", "state": "setting_aside", "revision": 7, "counts": { "setAside": 1840, "free": 1840, "held": 0, "booked": 0, "released": 0 }, "notFreeOnEveryDate": { "count": 12, "sample": [{ "eventKey": "ev_3", "label": "C-14", "reason": "sold" }] }, "windowEnded": false, "scheduledRelease": null, "dates": [{ "eventKey": "ev_1", "state": "up_to_date", "behind": 0, "lastAppliedAt": "2026-11-20T10:00:01Z" }] }
}
```

- On an active season, block mode turns on by itself once every date has the
  seats. Then the job is `completed`, and `season.block.ready` is sent once. On a
  draft, the job is `completed` once every date has the seats, and Publish
  turns block mode on and sends `season.block.ready`.
- `block.mode` is how the season sells now: `block` once its seats are on,
  `per_hold` before. `block.state` is the set-aside: `none`, `setting_aside`,
  then `ready`.
- `block.counts.setAside` starts at the seats your packages price, less those
  you keep for single tickets, and drops as dates leave seats out. Once `state`
  is `ready`, every date has answered: it is the seats set aside on every date.
  A seat a date left out isn't counted; it is listed in `notFreeOnEveryDate`.
- The same request sent again answers the same job, with or without the same
  `Idempotency-Key`. A different selection once the block exists is `409 block_exists`.

**Read them.** `GET /v1/seasons/:key/block` answers `{ block }`, the same shape.
A season with no seats set aside reads `state: "none"`.

**Release them to single sale.** Release now, or at a set time with `at`. Release
on every date still to come, or on some dates with `eventKeys`. `scope` is
`{ "all": true }` or the `sectionIds`, `categoryKeys` or `labels` to release.
Held seats are released when their hold ends; booked seats are never released.
Send an `Idempotency-Key`, so a retry releases once.

```json title="POST /v1/seasons/sea_…/block/release"
{ "expectedRevision": 7, "scope": { "all": true }, "at": "2026-12-01T09:00:00Z", "reason": "End of the season window" }
```

The answer is `202` with a `season_block_release` job. It is `planning` until
`at`, then `completed`, or `cancelled` if the release is cancelled. Once it has
run, `season.block.released` is sent once, with the seats it released.

| Code | When |
|---|---|
| `409 season_block_not_enabled` | Season seats aren't turned on for this season |
| `409 season_block_packages` | Setting aside on a season with more than one package |
| `409 revision_mismatch` | `expectedRevision` isn't the season's revision |
| `409 season_not_draft_or_active` | The season is closed or archived |
| `409 block_exists` | The season already has its block |
| `422 block_selection_empty` | No priced seat is left after the seats kept for single tickets |
| `409 block_not_ready` | Releasing before the season sells from its block |
| `422 seat_not_in_block` | A seat named in `scope` isn't a season seat |

**Changes while seats are set aside.**
- From the set-aside until block mode is on, a change that would make the
  seats wrong is refused with `409 season_block_set_aside`: adding or removing
  a date, another package, a package pricing other categories, and date
  amendments other than a new time. A price change on the same categories is
  accepted and reaches every date's seats.
- In block mode, cancelling a date or marking it past first takes the date off
  every season seat. While that is still under way the answer is
  `202 {state: "finishing", code: "block_date_leave_pending", shardsLeft,
  shardCount}` with `Retry-After`. It finishes by itself; send the same request
  again to read how it ended.
- Block mode doesn't do these yet. Each answers `409 season_inventory_locked`,
  nothing changes, and the body's `action` names which:

  | `action` | Refused in block mode |
  |---|---|
  | `date_changes` | Adding or removing a package's date |
  | `amendments` | Postponing or replacing a date, or a cancel exception (a new time is accepted) |
  | `holder_cancel` | Cancelling a booking, from your server or the holder's page |
  | `date_cancel` | Taking one date back from a holder's order |
  | `returns` | Returning or reclaiming a date's seats |
  | `recovery` | Emergency recovery |

[Season seats errors](/server-api/errors/#season-seats) lists every code.

## Amendments, reports, and support

**GET /v1/seasons/:key/occurrences**. Authentication: Secret key
**POST /v1/seasons/:key/amendments**. Authentication: Secret key
**GET /v1/seasons/:key/amendments**. Authentication: Secret key
**GET /v1/seasons/:key/amendments/:amendmentId**. Authentication: Secret key
**GET /v1/seasons/:key/reports**. Authentication: Secret key
**GET /v1/seasons/:key/operations**. Authentication: Secret key
**GET /v1/seasons/:key/support-lookups**. Authentication: Secret key
**GET /v1/seasons/:key/outbox**. Authentication: Secret key
**POST /v1/seasons/:key/outbox/:occurrenceId/replay**. Authentication: Secret key

A `reschedule` may change Event date-time or name. It does **not** change Event
keys, Plan activation, or `occurrence_set_sha256`. Passing `eventKeys` that
would add or remove occurrences is `409 occurrence_membership_immutable`.
When more than one Plan is published, list occurrences with the exact
`planActivationId` query and include that activation in amendment requests;
omission is `409 plan_selection_required`.
Because Event schedule metadata is global, an Event shared by multiple
published Plans fails closed with `409 occurrence_shared_across_plans` until
every affected activation can be retained in one amendment audit record. No
`0.9.0` SDK sends the `planActivationId` query on the occurrence list, and only
PHP and Java send `planActivationId` on an amendment. With more than one
published Plan, list occurrences over REST, and send amendments over REST
unless you use PHP or Java.

Occurrence rows include nullable `latestAmendment` identity, kind, and
classification. Amendment list rows retain the full activation, occurrence set,
before/after state, contract outcomes, and allocation outcomes; they are
not reduced summaries.

`replace` and `cancel_exception` record operator-visible exceptions. They do
not silently rewrite the published Plan and they do not refund money.

```http title="reschedule"
POST /v1/seasons/sea_…/amendments
Authorization: Bearer sk_test_••••••••
Idempotency-Key: night-1-rain
Content-Type: application/json

{
  "eventKey": "ev_night_1",
  "kind": "reschedule",
  "startsAt": 1790000000000
}
```

Every server SDK sends this request. REST also takes `planActivationId` on
amendment creation; of the `0.9.0` SDKs, only PHP and Java send it.

`GET /reports` totals live inventory and catalogue counts. `GET /support-lookups?bookingRef=` returns bookings, offers,
and contracts. It never includes a refund. `GET /outbox` is the missed-event
feed; `POST /outbox/:occurrenceId/replay` resends the same payload.

## Duplicate to live

A test Season can be copied onto new live identities. Sales stay closed. Pass
the live Event keys that should replace the test occurrences:

```http title="duplicate"
POST /v1/seasons/sea_…/duplicate-to-live
Authorization: Bearer sk_test_••••••••
Idempotency-Key: 2026-series-live
Content-Type: application/json

{
  "name": "2026 series",
  "eventKeys": ["ev_live_1", "ev_live_2"]
}
```

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