From 8c2cfb5f6fab0a190ce9a57bea26cf09993f9d65 Mon Sep 17 00:00:00 2001 From: navin10sharma <3096611+navin10sharma@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:33:55 +0530 Subject: [PATCH 01/13] Link the public API reference in AGENTS.md --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8b3fe2b..978576c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,9 +7,9 @@ be usable from a browser. - **No runtime dependencies.** Uses `urllib` and `hmac` from the standard library only. Keep it that way — a server SDK that drags in a dependency tree is a supply-chain surface for every customer. -- **The public surface is defined upstream** by `workers/api/src/publicApi.ts` in the app repo. +- **The public surface is the SeatLayer server API**: [reference](https://docs.seatlayer.io/server-api/) and [OpenAPI document](https://docs.seatlayer.io/openapi.json). A method here must map to an operation listed there. Do not wrap internal routes. -- **Method names are the operationIds** from that manifest, snake_cased. Renaming one is a +- **Method names are the operationIds** in that OpenAPI document, snake_cased. Renaming one is a breaking change across every SeatLayer server SDK, not just this package. - **Ergonomics live here, not in the transport.** Things like "capabilities is required" and "expectedUpdatedAt is required" are deliberate divergences from the raw API; each one has a From 034e327fca62fb0df3840805ec1fe5efa9b3207e Mon Sep 17 00:00:00 2001 From: navin10sharma <3096611+navin10sharma@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:33:55 +0530 Subject: [PATCH 02/13] Update the performance summary --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 85f2238..a6d6c88 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ Two-step shape: the buyer picks and holds seats in the client with your public k ## Scale evidence -Benchmarked on public 100,000-, 150,000- and 200,000-seat venue fixtures on 15 September 2026: 200,000 seats chart-ready in 1.95 s, desktop, local production build. Fixtures, method and run logs: https://github.com/seatlayer/seatlayer-performance. Live 200,000-seat stadium demo: https://app.seatlayer.io/demo/play/century-stadium-200k. This is renderer evidence, not a concurrent-buyer claim. +Benchmarked on public 100,000-, 150,000- and 200,000-seat venue fixtures on 15 September 2026: 200,000 seats chart-ready in 1.95 s, desktop, local production build. Tested at 10,000 concurrent buyers on one event: seat hold p99 9 ms, zero server errors. Method, fixtures and raw runs: https://github.com/seatlayer/seatlayer-performance. Live 200,000-seat stadium demo: https://app.seatlayer.io/demo/play/century-stadium-200k. ## Install the Python seat booking SDK From 68f79dac8945eea378fe151980a459b12dfddb16 Mon Sep 17 00:00:00 2001 From: navin10sharma <3096611+navin10sharma@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:56:28 +0530 Subject: [PATCH 03/13] Correct the season operation count --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a6d6c88..012ae0c 100644 --- a/README.md +++ b/README.md @@ -88,11 +88,12 @@ live ones; crossing them returns `403 mode_mismatch`, surfaced as `SeatLayerAuth ## Fixed Renewable Seasons -`seatlayer.seasons` exposes all 87 trusted organizer operations: catalogue and packages, -performances, package prices (per price type: `adult`, `child`, `concession`, `senior`, -`student`), sales, checkout tests, buyer access and booking, holder imports, holders, season -orders, renewals, hosted renewals and renewal checkouts, occurrences (postpone and cancel a date), bulk refunds of a -cancelled date, the release of lapsed renewal offers and their jobs, reports, CSV exports, audit, outbox, and support export. +`seatlayer.seasons` has all 90 season operations: seasons and their packages, dates and +package prices (per price type: `adult`, `child`, `concession`, `senior`, `student`), sales +windows, checkout tests, buyer sessions and booking, holder imports and the holder list, +season orders, renewals (offers, quotes, intents, checkouts and hosted renewal links), date +changes and cancellations, season seats, bulk refunds with their jobs, sales and seat reports, +CSV exports, audit and support export. After the test hold/book/cancel journey and matching webhook deliveries, `validate_season_buyer_rehearsal(season_key)` sends no evidence body; SeatLayer @@ -484,7 +485,7 @@ holder, order, renewal, occurrence, reporting, export, outbox, and support opera | `webhooks` | `list` `create` `update` `delete` `list_deliveries` | | `workspaces` | `list` `create` `retrieve` `update` | | `performance_groups` | `list` `create` `retrieve` `delete` `activate` `close` `retrieve_lifecycle` `create_buyer_access_session` `list_buyer_access_sessions` `revoke_buyer_access_session` `retrieve_hold` `book_hold` `retrieve_booking` | -| `seasons` | 87 operations for catalogue and Plan lifecycle, performances, package prices, sales windows, checkout tests, buyer access and booking, holder imports, holders, season orders, renewals, hosted renewals and renewal checkouts, occurrence amendments, returns and reclaims, bulk refunds, lapsed offer release and jobs, reports, CSV exports, audit, outbox, and support export | +| `seasons` | 90 operations for catalogue and Plan lifecycle, performances, package prices, sales windows, checkout tests, buyer access and booking, holder imports, holders, season orders, renewals, hosted renewals and renewal checkouts, occurrence amendments, returns and reclaims, bulk refunds, lapsed offer release and jobs, reports, CSV exports, audit, outbox, and support export | | `holders` | `list_customers` `retrieve_holder` `update_holder` `revoke_holder_sessions` `list_holder_seasons` `list_holder_tickets` `retrieve_holder_ticket` `create_holder_transfer` `list_holder_transfers` `cancel_holder_transfer` `accept_holder_transfer` `create_holder_return` `create_holder_renewal_checkout` `decline_holder_renewal_offer` | | `orders` | `list_orders` `retrieve_order` `list_order_tickets` `list_event_orders` `retrieve_event_order` `export_event_orders_csv` `refund_event_order` `cancel_event_order` `resend_event_order_tickets` | | `event_series` | `create_event_series` `list_event_series` `retrieve_event_series` `add_event_series_dates` `update_event_series` | From e6af2c32b3e7e37a82d42c53fcc6f8d0dc488778 Mon Sep 17 00:00:00 2001 From: navin10sharma <3096611+navin10sharma@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:56:28 +0530 Subject: [PATCH 04/13] Correct the webhook event list wording --- README.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 012ae0c..53ea64d 100644 --- a/README.md +++ b/README.md @@ -368,11 +368,8 @@ For safe-mode embeds, pass `mode="safe"` with `safe_mode_options`; feature polic Subscription responses use the API envelopes exactly: `list()` returns `{"subs": [...]}`, `create()` returns `{"sub": ..., "secret": ...}` (the secret is shown once), and `update()` -returns `{"sub": ...}`. Supported event names are `seat.booked`, `seat.released`, `seat.blocked`, -`hold.expired`, `hold.created`, `hold.extended`, `event.created`, `event.soldout`, -`series.created`, `series.dates_added`, `order.paid`, `order.refunded`, `order.cancelled`, -`customer.created`, `customer.email_changed`, `season.ticket.transfer_sent`, -`season.ticket.transferred`, and `season.ticket.transfer_cancelled`. +returns `{"sub": ...}`. `WebhookEventName` lists every event name this version accepts, including +`season.block.ready` and `season.block.released`. Verify every delivery against the **raw** body. Re-serialising it changes the bytes and verification will fail. From f7b6f05672aaa047bdf5ffc92c5f85aaf976c20d Mon Sep 17 00:00:00 2001 From: navin10sharma <3096611+navin10sharma@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:56:28 +0530 Subject: [PATCH 05/13] Plain wording for the season sections --- README.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 53ea64d..587a618 100644 --- a/README.md +++ b/README.md @@ -95,12 +95,13 @@ season orders, renewals (offers, quotes, intents, checkouts and hosted renewal l changes and cancellations, season seats, bulk refunds with their jobs, sales and seat reports, CSV exports, audit and support export. -After the test hold/book/cancel journey and matching webhook deliveries, -`validate_season_buyer_rehearsal(season_key)` sends no evidence body; SeatLayer -discovers the retained chain automatically. Retrieved Season holds contain -inventory identity, not an authoritative amount. When you run your own checkout, -your platform owns package price, payment, order, tax, refunds, benefits, and -ticket or pass delivery. +Before you open sales, run one test hold, booking and cancellation with their +webhooks, then call `validate_season_buyer_rehearsal(season_key)`. It finds those +test records itself, so it takes no body. Until a test like this or a checkout +test has passed, opening sales answers with a `checkout_test_missing` warning. A +season hold lists each date's seat, category and quantity but no price: when you +run your own checkout, you set the package price and take the payment, and you +issue the tickets. ```python checked = seatlayer.seasons.validate_season( @@ -114,10 +115,13 @@ draft = seatlayer.seasons.create_season( activation = seatlayer.seasons.activate_season(draft["key"], draft["revision"]) ``` -Treat `202` as accepted work: retain the returned `lifecycleOperation.operationId` -and poll `retrieve_season_lifecycle`. Buyer sessions are show-once and never -retried invisibly. Booking, cancellation, and renewal actions require caller-stable -identities. Only header-replay mutations retry automatically. +A `202` answer means the work was accepted and is still running: keep the returned +operation id (`lifecycleOperation.operationId`) and poll +`retrieve_season_lifecycle` until it finishes. Bookings, cancellations and renewal +commits are sent once and never retried by the SDK, so give each one your own +stable id; sending the same id again is safe. A buyer session is sent once too, +but it cannot be repeated: if its answer is lost, revoke what was created and +create one new session. ```python seatlayer = SeatLayer(os.environ["SEATLAYER_SECRET_KEY"]) From e03ff2704eaddea5c36ed2c9566a902a79657253 Mon Sep 17 00:00:00 2001 From: navin10sharma <3096611+navin10sharma@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:56:28 +0530 Subject: [PATCH 06/13] Plain wording for capabilities and orders --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 587a618..eb77aea 100644 --- a/README.md +++ b/README.md @@ -337,16 +337,16 @@ The full set, all opt-in: |---|---| | `event:view` | Read the seat map and its live states | | `event:block` | Block and unblock seats | -| `event:cancel` | Cancel a Platform/SDK booking by reference and return its inventory to sale; does not move gateway money | +| `event:cancel` | Cancel a booking by its reference and put the seats back on sale; refunds nobody | | `event:reports` | Read sales and availability reports | | `event:channels:view` | Read sales channels and their allocations | | `event:channels:manage` | Create, pause and archive channels; rotate access links | -| `event:orders:read` | Read SeatLayer-managed orders | -| `event:refund` | Refund an eligible Managed Ticketing order through its connected gateway | -| `event:tickets:send` | Send SeatLayer-managed tickets | +| `event:orders:read` | Read the orders SeatLayer's checkout took | +| `event:refund` | Refund an order SeatLayer's checkout took, through its payment gateway | +| `event:tickets:send` | Send the tickets of an order SeatLayer's checkout took | | `event:door:view` | Read the door list | | `event:door:checkin` | Check tickets in and out | -| `event:boxoffice` | Use the managed box-office surface | +| `event:boxoffice` | Use SeatLayer's box office screen | The two `event:channels:*` capabilities are **not** in the default (a token minted before sales channels existed must not silently acquire channel authority), so ask for them explicitly if the From 14a0ed8cb9b1185f76efe9dec656334bf2451a7f Mon Sep 17 00:00:00 2001 From: navin10sharma <3096611+navin10sharma@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:56:28 +0530 Subject: [PATCH 07/13] Update the pricing line --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index eb77aea..dbdf4ef 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ and webhooks through one typed ticketing API client. Two-step shape: the buyer picks and holds seats in the client with your public key, then this SDK confirms the booking from your server with your secret key while your platform keeps checkout and its own payment provider. -**Start here:** [Quickstart](https://docs.seatlayer.io/start/quickstart/) · [Holds and checkout](https://docs.seatlayer.io/buyer-sdk/holds-and-checkout/) · [Python server SDK guide](https://docs.seatlayer.io/server-sdk/python/) · [SDK catalog](https://docs.seatlayer.io/sdk-catalog.json) · [Pricing](https://seatlayer.io/pricing/): $0 entry, 100 free confirmed-sold-seat credits per organization each month, then $0.10 down to $0.05 a credit, and credits never expire. +**Start here:** [Quickstart](https://docs.seatlayer.io/start/quickstart/) · [Holds and checkout](https://docs.seatlayer.io/buyer-sdk/holds-and-checkout/) · [Python server SDK guide](https://docs.seatlayer.io/server-sdk/python/) · [SDK catalog](https://docs.seatlayer.io/sdk-catalog.json) · [Pricing](https://seatlayer.io/pricing/): 100 sold seats free every month, then 10¢ down to 5¢ per sold seat. No subscription, and purchased credits never expire. Test mode is free. ## Scale evidence From b102c987f03980f303e2ce31c1810115e6163ce4 Mon Sep 17 00:00:00 2001 From: navin10sharma <3096611+navin10sharma@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:56:28 +0530 Subject: [PATCH 08/13] Update the payment provider answer --- README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index dbdf4ef..96f7725 100644 --- a/README.md +++ b/README.md @@ -539,12 +539,11 @@ outcome before trying again. ### Can I use my own payment provider? -Yes. This server SDK does not process payment in a Platform/SDK integration. Inspect the hold, -compute the charge from each returned item's authoritative `unitPrice`, `quantity`, and `currency`, -take the money through whichever provider you already use, and then book the hold with your order -id as `booking_ref`. SeatLayer owns seating state, holds, booking concurrency, and the inventory -ledger in this integration; your platform owns payments, commercial orders, tickets, delivery, -and refunds. Managed Ticketing is a separate product path with organizer-connected payments. +Yes. Nothing in this SDK takes a payment: your server charges the hold's total through the provider +you already use, then books the seats with your order id as `booking_ref`, and SeatLayer never +touches the money. If you would rather SeatLayer run the checkout for an event +(`events.replace_event_buyer_checkout`), buyers pay through one of 14 payment gateways, including +Stripe, PayPal and Square, straight into your own account. ## Continue your Python integration From 6db90e7284219cc5d7cb09d452fe7178f135b686 Mon Sep 17 00:00:00 2001 From: navin10sharma <3096611+navin10sharma@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:56:28 +0530 Subject: [PATCH 09/13] Correct the Python season helper call --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 96f7725..11b010b 100644 --- a/README.md +++ b/README.md @@ -184,8 +184,9 @@ seatlayer.seasons.release_season_block( `season.block.released` is sent once a release has run. - In block mode, a date cancel (`create_season_amendment`, kind `"cancel"`) or `mark_season_performance_past` first takes the date off every season seat. Until that finishes - the answer is a `202`: check it with `seatlayer.is_season_date_leave_pending(answer)`, then send - the same request again after `Retry-After`. + the answer is a `202`: check it with `is_season_date_leave_pending(answer)` + (`from seatlayer import is_season_date_leave_pending`), then send the same request again after + `Retry-After`. - Refusals come through `SeatLayerError` with `code`, and nothing changes. For example `409 season_block_packages` (more than one package), `409 season_block_on_sale` (sales have opened), or `409 block_not_ready` from `open_season_sales` before block mode is on. From 401e774bb7d9f893f452204b5080ba3fe0d1230c Mon Sep 17 00:00:00 2001 From: navin10sharma <3096611+navin10sharma@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:56:28 +0530 Subject: [PATCH 10/13] Replace the two-step line with how it works --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 11b010b..3b8d587 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ and webhooks through one typed ticketing API client. > **Server-side only.** This package authenticates with your secret key. Never run it anywhere a > ticket buyer can reach. Browser surfaces get short-lived, origin-bound tokens that you mint here. -Two-step shape: the buyer picks and holds seats in the client with your public key, then this SDK confirms the booking from your server with your secret key while your platform keeps checkout and its own payment provider. +**How it works:** the buyer picks and holds seats in your website or app with your public key. Your server then reads the hold, takes the payment through your own provider, and books the seats with this SDK and your secret key. **Start here:** [Quickstart](https://docs.seatlayer.io/start/quickstart/) · [Holds and checkout](https://docs.seatlayer.io/buyer-sdk/holds-and-checkout/) · [Python server SDK guide](https://docs.seatlayer.io/server-sdk/python/) · [SDK catalog](https://docs.seatlayer.io/sdk-catalog.json) · [Pricing](https://seatlayer.io/pricing/): 100 sold seats free every month, then 10¢ down to 5¢ per sold seat. No subscription, and purchased credits never expire. Test mode is free. From ba9b007d40036d011eb8b91d7b23f8692212f4e3 Mon Sep 17 00:00:00 2001 From: navin10sharma <3096611+navin10sharma@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:56:28 +0530 Subject: [PATCH 11/13] Plain wording --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 3b8d587..fc391be 100644 --- a/README.md +++ b/README.md @@ -448,10 +448,10 @@ mutations opt into exact header replay: `charts.create`, `charts.copy`, reuses it for every attempt. All remaining SDK mutations are sent once; some have a server-side domain idempotency contract, but the SDK does not retry them automatically. -**Booking safety.** Direct and box-office bookings have the server's exact-selection plus -`booking_ref` safeguard, but the SDK still sends them once. Holds, best-available operations, -show-once secret creation and raw mutations are also single-attempt; reconcile an unknown outcome -before trying again. +**Booking safety.** Sending the same direct or box-office booking again with the same +`booking_ref` never sells a seat twice, but the SDK still sends each booking once. Holds, +best-available operations, show-once secret creation and raw mutations are also single-attempt; +reconcile an unknown outcome before trying again. ```python SeatLayer( @@ -500,12 +500,12 @@ Some API surface is intentionally unwrapped, not merely pending: - **Connecting payment gateways.** Connecting one is a dashboard flow. Once a gateway is connected, `events.replace_event_payment_gateway` assigns it to an event. -- **Realtime seat updates.** Live seat state reaches the *browser* through the widget's own socket. - There is no server-side subscribe; a secret-key caller gets authoritative state from - `events.retrieve_report()` and `inventory.retrieve_availability()`. +- **Realtime seat updates.** Live seat changes reach buyers through the seat map itself. There is + no server-side live feed; a server reads the current state with `events.retrieve_report()` and + `inventory.retrieve_availability()`. -None of these are reachable through `request()` as a supported path either; they are excluded from -the public manifest, not just from the wrapper. +Neither of these two (connecting a gateway, a server-side live feed) is part of the public API, so +`request()` does not support them either. ## Frequently asked questions From 147c8f29581f9cf11c5ba6c1e58e107e00654006 Mon Sep 17 00:00:00 2001 From: navin10sharma <3096611+navin10sharma@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:58:41 +0530 Subject: [PATCH 12/13] Plain wording for the payment gateway note --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index fc391be..4deabca 100644 --- a/README.md +++ b/README.md @@ -498,13 +498,13 @@ Full reference: [SeatLayer server API events](https://docs.seatlayer.io/server-a Some API surface is intentionally unwrapped, not merely pending: -- **Connecting payment gateways.** Connecting one is a dashboard flow. Once a gateway is connected, - `events.replace_event_payment_gateway` assigns it to an event. +- **Payment gateways.** A gateway is set up in the SeatLayer dashboard, not through this SDK. Once + it is set up, `events.replace_event_payment_gateway` assigns it to an event. - **Realtime seat updates.** Live seat changes reach buyers through the seat map itself. There is no server-side live feed; a server reads the current state with `events.retrieve_report()` and `inventory.retrieve_availability()`. -Neither of these two (connecting a gateway, a server-side live feed) is part of the public API, so +Neither of these two (setting up a gateway, a server-side live feed) is part of the public API, so `request()` does not support them either. ## Frequently asked questions From 7c7d5691786ad76065286494200f97f85bde6154 Mon Sep 17 00:00:00 2001 From: navin10sharma <3096611+navin10sharma@users.noreply.github.com> Date: Tue, 17 Nov 2026 21:11:35 +0530 Subject: [PATCH 13/13] Correct the performance summary and the season notes --- README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 4deabca..e74281f 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ and webhooks through one typed ticketing API client. ## Scale evidence -Benchmarked on public 100,000-, 150,000- and 200,000-seat venue fixtures on 15 September 2026: 200,000 seats chart-ready in 1.95 s, desktop, local production build. Tested at 10,000 concurrent buyers on one event: seat hold p99 9 ms, zero server errors. Method, fixtures and raw runs: https://github.com/seatlayer/seatlayer-performance. Live 200,000-seat stadium demo: https://app.seatlayer.io/demo/play/century-stadium-200k. +Benchmarked on public 100,000-, 150,000- and 200,000-seat venue fixtures on 15 September 2026: 200,000 seats chart-ready in 1.95 s, desktop, local production build. Tested at 10,000 simulated concurrent buyers on one 12,000-seat event (18 September 2026): engine-side hold latency p99 9 ms, zero server errors. Method, fixtures and run files: https://github.com/seatlayer/seatlayer-performance. Live 200,000-seat stadium demo: https://app.seatlayer.io/demo/play/century-stadium-200k. ## Install the Python seat booking SDK @@ -97,8 +97,7 @@ CSV exports, audit and support export. Before you open sales, run one test hold, booking and cancellation with their webhooks, then call `validate_season_buyer_rehearsal(season_key)`. It finds those -test records itself, so it takes no body. Until a test like this or a checkout -test has passed, opening sales answers with a `checkout_test_missing` warning. A +test records itself, so it takes no body. With your own checkout, until a test like this or a checkout test has passed, opening sales answers with a `checkout_test_missing` warning. A season hold lists each date's seat, category and quantity but no price: when you run your own checkout, you set the package price and take the payment, and you issue the tickets. @@ -119,8 +118,7 @@ A `202` answer means the work was accepted and is still running: keep the return operation id (`lifecycleOperation.operationId`) and poll `retrieve_season_lifecycle` until it finishes. Bookings, cancellations and renewal commits are sent once and never retried by the SDK, so give each one your own -stable id; sending the same id again is safe. A buyer session is sent once too, -but it cannot be repeated: if its answer is lost, revoke what was created and +stable id; sending the same id again is safe. A buyer session is sent once too, and repeating it is not safe: if its answer is lost, revoke what was created and create one new session. ```python