Season 2a server operations (part A)

CHANGELOG.md

@@ -1,5 +1,81 @@
 # Changelog
 
+## Unreleased
+
+- A date its season cancelled never opens again: `transitionEventSales` to `testable` or `live`
+  and `reopen` answer `409 season_date_cancelled`, and `updateEventSeries` with `sales` `on`
+  leaves it closed as a failed item of the job (`season_date_cancelled`; not in `failedDates`).
+- `createSeasonAmendment` refuses to move (`reschedule`), postpone or replace a cancelled date,
+  and `markSeasonPerformancePast` refuses to mark one as taken place:
+  `409 performance_cancelled`.
+- `updateEventSeries` sends only the prices that change: each date keeps its own price for every
+  category (or tier) left out, so weekend and weekday prices keep their difference; its
+  `categories` is typed `non-empty-list`.
+- A season's `transferCutoffHours` / `returnCutoffHours` of `null` means the club default
+  (Settings › Ticket site), or until the date starts when the club has none.
+- `createHolderTransfer` and `createHolderReturn` are not stopped by the club's customer switches
+  in Settings › Ticket site; cut-offs still apply.
+- Cancelling a date voids its tickets as a `date_cancel_void` job, named by
+  `Seasons::dateCancelVoidJobId($amendmentId)` (`sbj_void_…`) and followed with
+  `retrieveSeasonBulkJob`; `season.ticket.voided` says `date_cancelled` for each season ticket
+  it voids.
+- A Season package holds 2 to 50 dates. `Seasons::holderImportRowsPerCall($dates)` gives the
+  most rows one `createSeasonHolderImport` call takes (100 up to 20 dates, 43 at 50); a call
+  with more answers `422 invalid_rows` with `maxRows` in the exception's `body`.
+- `updateSeason`'s `singleTicketDates` can carry `jobRefused`, why a `season_singles` job could
+  not start; the change stands, and sending `singleTickets` true again opens any date still not
+  open. An `updateSeason` retried with its first key and `expectedRevision` is not applied twice.
+- A series create given up for its key answers `409 create_abandoned` (a `ConflictException`)
+  with a message to send it again with a new idempotency key.
+
+- Added the 39 remaining Season organizer operations to `$seatlayer->seasons`, which now
+  has 87: performances and packages (`createSeasonPerformances`, `attachSeasonPerformances`,
+  `updateSeasonPlan`, `deleteSeasonPlan`, `publishSeason`, and more), package prices,
+  checkout tests, occurrence returns and reclaims, `listSeasonHolders`, season order refunds,
+  cancellations and resends, hosted renewals, renewal links, contacts and notices, renewal
+  quotes, intents and checkouts, the sales,
+  seats and seat-count reports, holder and order CSV exports, and bulk refunds and lapsed-offer
+  releases with their jobs.
+- Added `$seatlayer->holders` (holder reads and updates, `listCustomers`, session sign-out,
+  tickets, and ticket transfers), `$seatlayer->orders` (orders across events and seasons, and
+  one event's orders with refund, cancel, resend, and CSV export), and `$seatlayer->eventSeries`
+  (plan a series from a schedule, add dates, change every upcoming date).
+- Added `holders->createHolderReturn`: give back a holder's seat on one date, one per ticket.
+- Added event sales settings to `$seatlayer->events`: buyer checkout, payment gateway, sales
+  readiness, preflight and transitions, booking fee, and discount codes.
+- Replay-backed operations send an `Idempotency-Key` (yours, or a generated one reused on
+  retry), as before; every other new mutation is sent once. The CSV exports return the CSV
+  text as a string, and the two `204` deletes return nothing.
+- Added `seasons->refundSeasonPerformance` (refund every order of a cancelled date as a job,
+  with header replay), `seasons->listSeasonBulkJobs`, and `seasons->retrieveSeasonBulkJob`.
+- `replaceSeasonPackagePrices` types `priceTypeKey` on each price (`adult`, `child`,
+  `concession`, `senior`, `student`).
+- `createSeasonAmendment` types the `postpone` and `cancel` kinds, with `refund` and `reason`.
+- `updateSeason` types `checkoutMode`, `transferCutoffHours`, and `returnCutoffHours`.
+- `createSeasonHolderImport` documents `holderEmail` and `holderName` on each row.
+- `events->list` and `events->listAll` take `seriesKey` to list one event series' dates.
+- Added `seasons->retrieveSeasonRenewalQuote`: what renewing an offer costs, and whether SeatLayer checkout can take it now.
+- Added `seasons->createSeasonRenewalIntent`: record a holder's intent for a renewal taken by phone or at the box office, so your own checkout can commit.
+- Added `seasons->createSeasonRenewalCheckout`: a SeatLayer checkout that renews an offer with no hosted page, with header replay.
+- Added `holders->createHolderRenewalCheckout`: the same checkout for one of a holder's offers, with header replay.
+- Added `holders->declineHolderRenewalOffer`: decline one of a holder's offers, with an optional reason.
+- `seasons->declineSeasonRenewalOffer` takes an optional `$reason`, kept on the offer as `declineReason`.
+- `updateSeason` takes `audience` (`embed_only` or `public`).
+- `openSeasonSales` answers `warnings` (`checkout_test_missing` until a checkout test or rehearsal has passed) and can refuse with `409 plan_not_published` or `409 checkout_mode_not_chosen`.
+- A cancelled date refunds per date only: an amendment's `refund` is `none` or `per_date`, and `refundSeasonPerformance` takes `amount` `per_date` (`full` answers `422 date_refund_per_date_only`; refund a whole order with the order refund).
+- `addEventSeriesDates` takes `['retryFailed' => true]` to make the failed dates again (`409 series_busy`, `422 nothing_to_retry`).
+- `listOrders` takes `$holderRef` (last argument); orders carry `holderRef` and `customerId`, and `buyer.email` can be null (a box office sale with no email).
+- Season holds, give-backs and date cancels can refuse with `performance_cancelled`, `refund_not_started` (503), `missing_manage_capability` (403) or `invalid_refund`; a holder's status can be `reserved`; hosted renewal readiness carries `missingPrices`.
+- `eventSeries->createEventSeries` takes `['fromEventKey' => …, 'schedule' => …]`: an event you already set up becomes the first date under its own key, and every other date is a copy of it. It refuses with `404 event_not_found`, or `422 event_has_no_date`, `event_in_season`, `event_in_performance_group`, `event_in_series` or `invalid_request`.
+- Every date of an event series carries the series' plain name (`Hamlet`, not `Hamlet · 3 Nov`); tell dates apart by `startsAt`. `updateEventSeries` renames each date that carries the series name, and a series name cannot hold `{n}`, `{date}` or `{time}`.
+- Added `seasons->releaseSeasonLapsedOffers`: release the seats of every lapsed renewal offer as a job (`202` with `job`), with header replay. An offer extended before its turn is skipped and keeps its seat.
+- `retrieveSeasonHostedRenewals` and `listSeasonRenewalOffers` take `$cursor` and `$limit` (last arguments) and answer `nextCursor`, null on the last page: up to 500 offers a page for hosted renewals (the default), 100 for the offer list. A bad cursor or limit answers `400 invalid_cursor` or `invalid_limit`.
+- `createSeasonRenewalOffers` answers `201` with `offers` for 100 contracts or fewer, and `202` with `job` and `batchId` above that: a `renewal_run` job makes the offers. Follow it with `retrieveSeasonBulkJob`, then page the offers with `listSeasonRenewalOffers`.
+- `createSeasonHolderImportFromSeason` answers `202` with a `holder_import` `job` when a commit brings across more than 100 holders; the completed job's `summary` has the same counts. Both creates can refuse with `409 job_mismatch` or `503 season_not_configured`, and the bring-across with `503 job_busy`.
+- `createSeasonRenewalNotices` takes up to 20,000 offer ids; above that it answers `422 too_many_offer_ids`.
+- `createSeasonRenewalNotices` takes `$batchId` (last argument) instead of `$offerIds`: email every open offer one `createSeasonRenewalOffers` batch made, such as the batch a `renewal_run` job made.
+- Single tickets on a season: `createSeason` and `updateSeason` take `singleTickets` in their params (default `false`, Season only; anything else answers `422 invalid_single_tickets`). Every season read carries `singleTickets`, and a season on sale may carry `singleTicketsNotOpen`. `updateSeason`, `openSeasonSales` and `resumeSeasonSales` answer `singleTicketDates` (`direction`, `opened`, `closed`, `notOpened`, `jobId`) when they open or stop the dates' own sales; a `season_singles` job does it for more than 12 upcoming dates.
+
 ## 0.8.0 (2026-09-10)
 
 - Added Event hosting regions: `$region` on event create, `$defaultRegion` on workspace create and update, and the `EventHostingRegion` constants. Events created without a region run in Western Europe.

README.md

@@ -78,8 +78,14 @@ The hint is best effort, not a data-residency guarantee. See the
 
 ## Fixed Renewable Seasons
 
-Version `0.7.0` exposes all 48 trusted organizer operations through
-`$seatlayer->seasons`.
+`$seatlayer->seasons` exposes 87 trusted organizer operations: the 48 released in `0.7.0`,
+plus performances and packages, package prices (each may name a `priceTypeKey`: `adult`,
+`child`, `concession`, `senior` or `student`), checkout tests, occurrence returns and
+reclaims, holders, season orders, hosted renewals, renewal quotes, intents and checkouts,
+sales and seat reports, CSV exports, and
+the bulk refund of a cancelled date (`refundSeasonPerformance`) and the release of every
+lapsed renewal offer's seats (`releaseSeasonLapsedOffers`) with their jobs
+(`listSeasonBulkJobs`, `retrieveSeasonBulkJob`).
 
 After the test hold/book/cancel journey and matching webhook deliveries,
 `validateSeasonBuyerRehearsal($seasonKey)` sends no evidence body; SeatLayer
@@ -103,6 +109,59 @@ returned operation identity. Buyer-session minting and domain-exact booking,
 cancellation, and renewal actions remain single-attempt; only declared
 header-replay catalogue mutations retry automatically.
 
+Above 100 contracts, `createSeasonRenewalOffers()` answers `202` with a `renewal_run` `job`
+and its `batchId` instead of `offers`; above 100 holders, `createSeasonHolderImportFromSeason()`
+answers `202` with a `holder_import` `job`. Follow either with `retrieveSeasonBulkJob()`.
+`listSeasonRenewalOffers()` and `retrieveSeasonHostedRenewals()` read one page at a time: pass
+the answer's `nextCursor` back as `$cursor` until it is null.
+
+`exportSeasonHoldersCsv()` and `exportSeasonOrdersCsv()` return the CSV text as a string,
+not decoded JSON. `deleteSeasonPlan()` returns nothing (the API answers `204`).
+
+When SeatLayer takes the season's payments, renew a holder with no hosted page: read the price,
+start a checkout, and send the holder to `payment.url`. For a renewal taken by phone or at the
+box office, `createSeasonRenewalIntent()` records the holder's intent before you commit the
+offer. A decline can carry the holder's reason.
+
+```php
+$quote = $seatlayer->seasons->retrieveSeasonRenewalQuote($seasonKey, $offerId);
+if ($quote['problem'] === null) {
+    $started = $seatlayer->seasons->createSeasonRenewalCheckout(
+        $seasonKey,
+        $offerId,
+        ['returnUrl' => 'https://tickets.yourclub.example/renewed'],
+        "renew-{$offerId}",
+    );
+    header('Location: ' . $started['payment']['url']);
+}
+
+$seatlayer->holders->declineHolderRenewalOffer('holder_123', $offerId, 'Moving away');
+```
+
+## Orders, holders, event sales, and event series
+
+- `$seatlayer->orders` lists orders across events and seasons, reads one order and its
+  tickets, and lists, refunds, cancels, or resends one event's orders.
+  `exportEventOrdersCsv()` returns the CSV text.
+- `$seatlayer->holders` reads and updates season ticket holders, finds customers with
+  `listCustomers()`, signs a holder out, lists their seasons and tickets, and sends,
+  cancels, or accepts ticket transfers.
+- `$seatlayer->events` also holds each event's sales settings: buyer checkout, payment
+  gateway, sales readiness, preflight and transitions, booking fee, and discount codes.
+- `$seatlayer->eventSeries` plans a series of dated events from a schedule, adds dates,
+  and changes every upcoming date at once.
+
+```php
+$paid = $seatlayer->orders->listEventOrders($eventKey, status: 'paid');
+$seatlayer->orders->refundEventOrder(
+    $eventKey,
+    $orderId,
+    amountMinor: 500,
+    idempotencyKey: "refund-{$refundId}",
+);
+$csv = $seatlayer->orders->exportEventOrdersCsv($eventKey); // CSV text
+```
+
 ## Test vs live
 
 Keys carry their own mode. `sk_test_…` keys can only touch test-mode events and `sk_live_…` only
@@ -206,6 +265,8 @@ exactly when you don't want that, and you can control it explicitly:
 $seatlayer->events->list(limit: 50, counts: false);
 ```
 
+Pass `seriesKey: 'ser_1'` to list only the dates of one event series.
+
 ## Keeping a hold alive
 
 When an order takes longer than the checkout window (an invoice, a phone sale), extend rather than
@@ -320,14 +381,25 @@ support requests.
 ## Reliability
 
 **Retries and idempotency.** Reads (`GET`/`HEAD`) retry connection failures, 408, 429 and 5xx with
-exponential backoff and full jitter; `Retry-After` wins when the server sends it. Fourteen mutations
-use exact header replay: `charts->create`, `charts->copy`,
-`templates->instantiateTemplate`, `events->create`, `workspaces->create`,
-`performanceGroups->create`, `seasons->createSeason`, `seasons->updateSeason`,
-`seasons->deleteSeason`, `seasons->createSeasonPlan`, `seasons->duplicateSeasonToLive`,
-`seasons->createSeasonHolderImport`, `seasons->createSeasonRenewalOffers`, and
-`seasons->createSeasonAmendment`. They generate an `Idempotency-Key` when absent and reuse that key
-across every attempt. You can supply a stable provisioning key instead:
+exponential backoff and full jitter; `Retry-After` wins when the server sends it. Forty-one
+mutations use exact header replay:
+
+- `charts->create`, `charts->copy`, `templates->instantiateTemplate`, `events->create`,
+  `workspaces->create`, and `performanceGroups->create`;
+- on `seasons`: `createSeason`, `updateSeason`, `deleteSeason`, `publishSeason`,
+  `createSeasonPlan`, `updateSeasonPlan`, `deleteSeasonPlan`, `duplicateSeasonToLive`,
+  `createSeasonPerformances`, `attachSeasonPerformances`, `deleteSeasonPerformance`,
+  `markSeasonPerformancePast`, `attachSeasonPlanPerformance`, `deleteSeasonPlanPerformance`,
+  `replaceSeasonPackagePrices`, `createSeasonCheckoutTest`, `createSeasonHolderImport`,
+  `createSeasonHolderImportFromSeason`, `createSeasonRenewalOffers`, `createSeasonAmendment`,
+  `refundSeasonOrder`, `cancelSeasonOrder`, `cancelSeasonOrderDate`,
+  `refundSeasonPerformance`, `releaseSeasonLapsedOffers`, and `createSeasonRenewalCheckout`;
+- `holders->updateHolder`, `holders->createHolderTransfer`, `holders->createHolderReturn`,
+  `holders->createHolderRenewalCheckout`, `orders->refundEventOrder`, `orders->cancelEventOrder`, `eventSeries->createEventSeries`,
+  `eventSeries->addEventSeriesDates`, and `eventSeries->updateEventSeries`.
+
+They generate an `Idempotency-Key` when absent and reuse that key across every attempt. You can
+supply a stable provisioning key instead:
 
 ```php
 $seatlayer->events->create(
@@ -338,7 +410,8 @@ $seatlayer->events->create(
 ```
 
 All remaining SDK mutations are single-attempt: holds, bookings, lifecycle changes, channel
-changes, show-once secret creation, and raw requests. Some have a server-side domain idempotency
+changes, event sales settings and discount codes, ticket and renewal emails, show-once secret
+creation, and raw requests. Some have a server-side domain idempotency
 contract, but the SDK does not retry them automatically. Reconcile bookings with their required
 `bookingRef`; never retry an unknown booking outcome as though the transport had made it safe.
 
@@ -365,21 +438,24 @@ suite runs without a network.
 ## API surface
 
 The client exposes these resources. Performance Groups cover runs, sessions, holds, and bookings;
-Seasons cover catalogue, plan, sales, buyer-session, booking, renewal, occurrence, reporting,
-outbox, and support operations.
+Seasons cover catalogue, plan, performance, price, sales, buyer-session, booking, renewal,
+occurrence, holder, order, reporting, outbox, and support operations.
 
 | Resource | Methods |
 | --- | --- |
 | `charts` | `list` `listAll` `create` `retrieve` `update` `delete` `copy` `archive` `unarchive` `publish` |
 | `templates` | `instantiateTemplate` |
-| `events` | `list` `listAll` `create` `retrieve` `retrieveConfigurationBinding` `updateConfigurationBinding` `update` `delete` `updateChart` `close` `reopen` `archive` `retrieveHoldTtl` `updateHoldTtl` `listTicketReleases` `updateTicketReleases` `closeTicketRelease` `retrieveReport` `retrieveLog` |
+| `events` | `list` `listAll` `create` `retrieve` `retrieveConfigurationBinding` `updateConfigurationBinding` `update` `delete` `updateChart` `close` `reopen` `archive` `retrieveHoldTtl` `updateHoldTtl` `listTicketReleases` `updateTicketReleases` `closeTicketRelease` `retrieveReport` `retrieveLog` `retrieveEventBuyerCheckout` `replaceEventBuyerCheckout` `retrieveEventPaymentGateway` `replaceEventPaymentGateway` `retrieveEventSalesReadiness` `preflightEventSales` `transitionEventSales` `retrieveEventBookingFee` `replaceEventBookingFee` `listEventDiscountCodes` `createEventDiscountCode` `updateEventDiscountCode` `endEventDiscountCode` `deleteEventDiscountCode` |
+| `eventSeries` | `createEventSeries` `listEventSeries` `retrieveEventSeries` `addEventSeriesDates` `updateEventSeries` |
+| `orders` | `listOrders` `retrieveOrder` `listOrderTickets` `listEventOrders` `retrieveEventOrder` `exportEventOrdersCsv` `refundEventOrder` `cancelEventOrder` `resendEventOrderTickets` |
+| `holders` | `listCustomers` `retrieveHolder` `updateHolder` `revokeHolderSessions` `listHolderSeasons` `listHolderTickets` `retrieveHolderTicket` `createHolderTransfer` `listHolderTransfers` `cancelHolderTransfer` `acceptHolderTransfer` `createHolderReturn` `createHolderRenewalCheckout` `declineHolderRenewalOffer` |
 | `channels` | `listChannels` `createChannel` `updateChannel` `updateAssignments` `listAllocation` `retrieveAccessPreview` `retrieveReport` `pause` `unpause` `archive` `createBuyerAccessSession` `listBuyerAccessSessions` `revokeBuyerAccessSession` |
 | `inventory` | `hold` `holdBestAvailable` `bookBestAvailable` `extendHold` `retrieveHold` `release` `book` `boxOfficeBook` `unbook` `block` `unblock` `unblockAll` `retrieveAvailability` `updateAvailability` `listBookings` `retrieveBooking` |
 | `sessions` | `createManageSession` `revokeManageSession` `createDesignerSession` `revokeDesignerSession` |
 | `webhooks` | `list` `create` `update` `delete` `listDeliveries` |
 | `workspaces` | `list` `create` `retrieve` `update` |
 | `performanceGroups` | `list` `create` `retrieve` `delete` `activate` `close` `retrieveLifecycle` `createBuyerAccessSession` `listBuyerAccessSessions` `revokeBuyerAccessSession` `retrieveHold` `bookHold` `retrieveBooking` |
-| `seasons` | 48 operations for catalogue and Plan lifecycle, sales windows, buyer access and booking, holder imports, renewals, occurrence amendments, reports, audit, outbox, and support export |
+| `seasons` | 87 operations for catalogue and Plan lifecycle, performances and packages, package prices, checkout tests, sales windows, buyer access and booking, holder imports, holders, season orders, renewals, hosted renewals and renewal checkouts, occurrence amendments, returns and reclaims, bulk refunds, lapsed-offer releases and jobs, reports and CSV exports, audit, outbox, and support export |
 
 Full reference: [SeatLayer PHP server SDK guide](https://docs.seatlayer.io/server-sdk/php/)