seatschart 0.3.0 → 0.5.0

data/lib/seatschart/api/seats_api.rb

@@ -374,7 +374,7 @@ module SeatsChart
     end
 
     # Hold GA area capacity (Redis)
-    # Places a temporary hold on unnumbered GA capacity. **Idempotency-Key** is required; repeats within ~24h return the cached hold response. Optional `ticketBuyerId` is stored on the GA hold token and inherited by `POST /ga/confirm`. The organizer's booking limits cap `quantity` (designer *Max GA tickets per order*, else *Max seats per order*; strictest with the sales-channel default): 409 `booking_limit_exceeded` (`limit`, `current`, `requested`, `kind: \"ga\"`). GA tables sold as a whole (`shape.bookAs: \"whole\"`) take every place in one hold: any other `quantity` answers 409 `ga_table_whole` (`capacity`, `requested`). Areas sold as a whole (`areaType` `fixedOccupancy` / `variableOccupancy`) are held for one buyer in one piece: `quantity` is the number of people (fixed: exactly the capacity; variable: `minOccupancy`..capacity), every place of the area is held atomically and a second buyer can never hold part of it. Any other quantity answers 400 `ga_area_whole` (`areaType`, `capacity`, `minOccupancy`, `maxOccupancy`, `requested`); an area already held, sold or partly withheld answers 409 `conflict`. A whole area counts as one object against the booking limits (its capacity, at most 50, caps it); its people count against quotas, lots and per-buyer limits. The response adds `places`, `people` and `areaType`.
+    # Places a temporary hold on unnumbered GA capacity. **Idempotency-Key** is required; repeats within ~24h return the cached hold response. Optional `ticketBuyerId` is stored on the GA hold token and inherited by `POST /ga/confirm`. The organizer's booking limits cap `quantity` (designer *Max GA tickets per order*, else *Max seats per order*; strictest with the sales-channel default): 409 `booking_limit_exceeded` (`limit`, `current`, `requested`, `kind: \"ga\"`). **Free (test plan) out of seats:** once the workspace used its 50 seats of the month, new holds (appends included) answer 409 `holds_paused` with a neutral message until the next UTC month or an upgrade; holds already taken can still be confirmed. GA tables sold as a whole (`shape.bookAs: \"whole\"`) take every place in one hold: any other `quantity` answers 409 `ga_table_whole` (`capacity`, `requested`). Areas sold as a whole (`areaType` `fixedOccupancy` / `variableOccupancy`) are held for one buyer in one piece: `quantity` is the number of people (fixed: exactly the capacity; variable: `minOccupancy`..capacity), every place of the area is held atomically and a second buyer can never hold part of it. Any other quantity answers 400 `ga_area_whole` (`areaType`, `capacity`, `minOccupancy`, `maxOccupancy`, `requested`); an area already held, sold or partly withheld answers 409 `conflict`. A whole area counts as one object against the booking limits (its capacity, at most 50, caps it); its people count against quotas, lots and per-buyer limits. The response adds `places`, `people` and `areaType`.
     # @param idempotency_key [String] Required. Reuse with the same request on retry; a different payload conflicts. Seat confirmation binds this key durably in PostgreSQL; hold mutations use bounded Redis receipts.
     # @param post_api_ga_reserve_request [PostApiGaReserveRequest] 
     # @param [Hash] opts the optional parameters
@@ -385,7 +385,7 @@ module SeatsChart
     end
 
     # Hold GA area capacity (Redis)
-    # Places a temporary hold on unnumbered GA capacity. **Idempotency-Key** is required; repeats within ~24h return the cached hold response. Optional `ticketBuyerId` is stored on the GA hold token and inherited by `POST /ga/confirm`. The organizer's booking limits cap `quantity` (designer *Max GA tickets per order*, else *Max seats per order*; strictest with the sales-channel default): 409 `booking_limit_exceeded` (`limit`, `current`, `requested`, `kind: \"ga\"`). GA tables sold as a whole (`shape.bookAs: \"whole\"`) take every place in one hold: any other `quantity` answers 409 `ga_table_whole` (`capacity`, `requested`). Areas sold as a whole (`areaType` `fixedOccupancy` / `variableOccupancy`) are held for one buyer in one piece: `quantity` is the number of people (fixed: exactly the capacity; variable: `minOccupancy`..capacity), every place of the area is held atomically and a second buyer can never hold part of it. Any other quantity answers 400 `ga_area_whole` (`areaType`, `capacity`, `minOccupancy`, `maxOccupancy`, `requested`); an area already held, sold or partly withheld answers 409 `conflict`. A whole area counts as one object against the booking limits (its capacity, at most 50, caps it); its people count against quotas, lots and per-buyer limits. The response adds `places`, `people` and `areaType`.
+    # Places a temporary hold on unnumbered GA capacity. **Idempotency-Key** is required; repeats within ~24h return the cached hold response. Optional `ticketBuyerId` is stored on the GA hold token and inherited by `POST /ga/confirm`. The organizer's booking limits cap `quantity` (designer *Max GA tickets per order*, else *Max seats per order*; strictest with the sales-channel default): 409 `booking_limit_exceeded` (`limit`, `current`, `requested`, `kind: \"ga\"`). **Free (test plan) out of seats:** once the workspace used its 50 seats of the month, new holds (appends included) answer 409 `holds_paused` with a neutral message until the next UTC month or an upgrade; holds already taken can still be confirmed. GA tables sold as a whole (`shape.bookAs: \"whole\"`) take every place in one hold: any other `quantity` answers 409 `ga_table_whole` (`capacity`, `requested`). Areas sold as a whole (`areaType` `fixedOccupancy` / `variableOccupancy`) are held for one buyer in one piece: `quantity` is the number of people (fixed: exactly the capacity; variable: `minOccupancy`..capacity), every place of the area is held atomically and a second buyer can never hold part of it. Any other quantity answers 400 `ga_area_whole` (`areaType`, `capacity`, `minOccupancy`, `maxOccupancy`, `requested`); an area already held, sold or partly withheld answers 409 `conflict`. A whole area counts as one object against the booking limits (its capacity, at most 50, caps it); its people count against quotas, lots and per-buyer limits. The response adds `places`, `people` and `areaType`.
     # @param idempotency_key [String] Required. Reuse with the same request on retry; a different payload conflicts. Seat confirmation binds this key durably in PostgreSQL; hold mutations use bounded Redis receipts.
     # @param post_api_ga_reserve_request [PostApiGaReserveRequest] 
     # @param [Hash] opts the optional parameters
@@ -621,7 +621,7 @@ module SeatsChart
     end
 
     # Suggest or atomically hold best available seats
-    # Returns seat IDs for the requested quantity, preferring adjacent same-row groups near the map center. Filter the candidate pool by `category` (or ordered `categories`, max 10: windows of the first category are tried before the second, and so on), optional `sectionId` (layout section id or name) and optional `zone` (layout zone id or name; seats resolve explicit zone assignment, then their section zone, then the zone outline) before ranking. `tryToPreventOrphanSeats` (default **true**) skips adjacent windows that would leave a single empty seat at either end of the run, falling back to them only when nothing else fits. `ticketTypes` (`{ ticketTypeId: count }`) sets `quantity` to the sum, restricts the search to categories whose ticket catalog offers every requested type, and returns `ticketTypes` (seatId → ticketTypeId) ready to send as `seatTicketTypes` on confirm; events without ticket types reject it. `accessibleSeats` (N) only returns windows containing at least N seats flagged `accessibility.wheelchair` in the published seat structure (409 when no such window exists). `channel` is salesChannel order limits only. Pass **`x-channel-key`** for inventory partitions — do not send the secret in the body. **`hold: false` (default):** suggest only — does not lock. **`hold: true`:** ranks up to 32 candidate windows across the category preferences, locks the first fit in one Lua call each (all-or-nothing per window), then O(cart) PG gates (available/forSale/channel; seats that are not for sale are never picked, not even resale-listed ones of non-propagating season members: those are bought by holding the seats of the listing); on gate failure releases only the locks it added. Requires **Idempotency-Key**, and `userId` unless `holdToken` is given. `holdToken` appends the seats to that existing hold session (same expiry bound; 409 `hold_token_conflict` when the session is expired, foreign, confirming or full). `extraData` is stored on the held seats (requires hold). Returns `hold_token` for confirm. The organizer's booking limits (designer *Max seats per order*) cap `quantity` and, with `holdToken`, the seats already on the token: best-available never picks more than allowed (409 `booking_limit_exceeded` with `limit`, `current`, `requested`). `sections` (max 20 section ids or names, XOR with `sectionId`) ranks across the union of those sections. **API keys / dashboard sessions only:** `channelKeys` (channel secret keys or ids) restricts the pool to public seats plus those channels, `ignoreChannels: true` allows every channel (both replace `x-channel-key`; buyers get 403). `orderId` (with `hold`) is stored on the held seats as `extraData.orderId` and echoed in the response; pass it as `externalOrderId` on confirm. **`status: \"booked\"`** (API keys with the `bookings` scope, or dashboard sessions allowed to change object statuses; buyers get 403) books the best window directly instead of holding it: the same administrative booking as POST /events/{eventId}/actions/book (one SQL transaction under the seat row locks; a seat held by a buyer is never taken; when a ranked window was taken meanwhile the next one is tried). Requires **Idempotency-Key**: the booking order id is derived from it, so a retry returns the same booking. `ticketTypes` are recorded per seat, `extraData` and `orderId` (as `extraData.orderId`) are stored on the booked seats. Response: `status: \"booked\"`, `booked: true`, `bookingOrderId` (cancel with POST /orders/{orderId}/cancel) and `objects` (status, extraData, orderId, ticketType per seat). `status: \"reservedByToken\"` is the same as `hold: true`. **`keepExtraData: true`** (hold or booked) keeps the seats' stored extraData and merges `extraData` / `orderId` on top instead of replacing it.
+    # Returns seat IDs for the requested quantity, preferring adjacent same-row groups near the map center. **Free (test plan) out of seats:** once the workspace used its 50 seats of the month, new holds (appends included) answer 409 `holds_paused` with a neutral message until the next UTC month or an upgrade; holds already taken can still be confirmed. Filter the candidate pool by `category` (or ordered `categories`, max 10: windows of the first category are tried before the second, and so on), optional `sectionId` (layout section id or name) and optional `zone` (layout zone id or name; seats resolve explicit zone assignment, then their section zone, then the zone outline) before ranking. `tryToPreventOrphanSeats` (default **true**) skips adjacent windows that would leave a single empty seat at either end of the run, falling back to them only when nothing else fits. `ticketTypes` (`{ ticketTypeId: count }`) sets `quantity` to the sum, restricts the search to categories whose ticket catalog offers every requested type, and returns `ticketTypes` (seatId → ticketTypeId) ready to send as `seatTicketTypes` on confirm; events without ticket types reject it. `accessibleSeats` (N) only returns windows containing at least N seats flagged `accessibility.wheelchair` in the published seat structure (409 when no such window exists). `channel` is salesChannel order limits only. Pass **`x-channel-key`** for inventory partitions — do not send the secret in the body. **`hold: false` (default):** suggest only — does not lock. **`hold: true`:** ranks up to 32 candidate windows across the category preferences, locks the first fit in one Lua call each (all-or-nothing per window), then O(cart) PG gates (available/forSale/channel; seats that are not for sale are never picked, not even resale-listed ones of non-propagating season members: those are bought by holding the seats of the listing); on gate failure releases only the locks it added. Requires **Idempotency-Key**, and `userId` unless `holdToken` is given. `holdToken` appends the seats to that existing hold session (same expiry bound; 409 `hold_token_conflict` when the session is expired, foreign, confirming or full). `extraData` is stored on the held seats (requires hold). Returns `hold_token` for confirm. The organizer's booking limits (designer *Max seats per order*) cap `quantity` and, with `holdToken`, the seats already on the token: best-available never picks more than allowed (409 `booking_limit_exceeded` with `limit`, `current`, `requested`). `sections` (max 20 section ids or names, XOR with `sectionId`) ranks across the union of those sections. **API keys / dashboard sessions only:** `channelKeys` (channel secret keys or ids) restricts the pool to public seats plus those channels, `ignoreChannels: true` allows every channel (both replace `x-channel-key`; buyers get 403). `orderId` (with `hold`) is stored on the held seats as `extraData.orderId` and echoed in the response; pass it as `externalOrderId` on confirm. **`status: \"booked\"`** (API keys with the `bookings` scope, or dashboard sessions allowed to change object statuses; buyers get 403) books the best window directly instead of holding it: the same administrative booking as POST /events/{eventId}/actions/book (one SQL transaction under the seat row locks; a seat held by a buyer is never taken; when a ranked window was taken meanwhile the next one is tried). Requires **Idempotency-Key**: the booking order id is derived from it, so a retry returns the same booking. `ticketTypes` are recorded per seat, `extraData` and `orderId` (as `extraData.orderId`) are stored on the booked seats. Response: `status: \"booked\"`, `booked: true`, `bookingOrderId` (cancel with POST /orders/{orderId}/cancel) and `objects` (status, extraData, orderId, ticketType per seat). `status: \"reservedByToken\"` is the same as `hold: true`. **`keepExtraData: true`** (hold or booked) keeps the seats' stored extraData and merges `extraData` / `orderId` on top instead of replacing it.
     # @param post_api_seats_best_available_request [PostApiSeatsBestAvailableRequest] 
     # @param [Hash] opts the optional parameters
     # @option opts [String] :idempotency_key Required on transactional routes. Reuse the same key for every retry of one logical operation; the API replays the stored outcome.
@@ -632,7 +632,7 @@ module SeatsChart
     end
 
     # Suggest or atomically hold best available seats
-    # Returns seat IDs for the requested quantity, preferring adjacent same-row groups near the map center. Filter the candidate pool by `category` (or ordered `categories`, max 10: windows of the first category are tried before the second, and so on), optional `sectionId` (layout section id or name) and optional `zone` (layout zone id or name; seats resolve explicit zone assignment, then their section zone, then the zone outline) before ranking. `tryToPreventOrphanSeats` (default **true**) skips adjacent windows that would leave a single empty seat at either end of the run, falling back to them only when nothing else fits. `ticketTypes` (`{ ticketTypeId: count }`) sets `quantity` to the sum, restricts the search to categories whose ticket catalog offers every requested type, and returns `ticketTypes` (seatId → ticketTypeId) ready to send as `seatTicketTypes` on confirm; events without ticket types reject it. `accessibleSeats` (N) only returns windows containing at least N seats flagged `accessibility.wheelchair` in the published seat structure (409 when no such window exists). `channel` is salesChannel order limits only. Pass **`x-channel-key`** for inventory partitions — do not send the secret in the body. **`hold: false` (default):** suggest only — does not lock. **`hold: true`:** ranks up to 32 candidate windows across the category preferences, locks the first fit in one Lua call each (all-or-nothing per window), then O(cart) PG gates (available/forSale/channel; seats that are not for sale are never picked, not even resale-listed ones of non-propagating season members: those are bought by holding the seats of the listing); on gate failure releases only the locks it added. Requires **Idempotency-Key**, and `userId` unless `holdToken` is given. `holdToken` appends the seats to that existing hold session (same expiry bound; 409 `hold_token_conflict` when the session is expired, foreign, confirming or full). `extraData` is stored on the held seats (requires hold). Returns `hold_token` for confirm. The organizer's booking limits (designer *Max seats per order*) cap `quantity` and, with `holdToken`, the seats already on the token: best-available never picks more than allowed (409 `booking_limit_exceeded` with `limit`, `current`, `requested`). `sections` (max 20 section ids or names, XOR with `sectionId`) ranks across the union of those sections. **API keys / dashboard sessions only:** `channelKeys` (channel secret keys or ids) restricts the pool to public seats plus those channels, `ignoreChannels: true` allows every channel (both replace `x-channel-key`; buyers get 403). `orderId` (with `hold`) is stored on the held seats as `extraData.orderId` and echoed in the response; pass it as `externalOrderId` on confirm. **`status: \"booked\"`** (API keys with the `bookings` scope, or dashboard sessions allowed to change object statuses; buyers get 403) books the best window directly instead of holding it: the same administrative booking as POST /events/{eventId}/actions/book (one SQL transaction under the seat row locks; a seat held by a buyer is never taken; when a ranked window was taken meanwhile the next one is tried). Requires **Idempotency-Key**: the booking order id is derived from it, so a retry returns the same booking. `ticketTypes` are recorded per seat, `extraData` and `orderId` (as `extraData.orderId`) are stored on the booked seats. Response: `status: \"booked\"`, `booked: true`, `bookingOrderId` (cancel with POST /orders/{orderId}/cancel) and `objects` (status, extraData, orderId, ticketType per seat). `status: \"reservedByToken\"` is the same as `hold: true`. **`keepExtraData: true`** (hold or booked) keeps the seats' stored extraData and merges `extraData` / `orderId` on top instead of replacing it.
+    # Returns seat IDs for the requested quantity, preferring adjacent same-row groups near the map center. **Free (test plan) out of seats:** once the workspace used its 50 seats of the month, new holds (appends included) answer 409 `holds_paused` with a neutral message until the next UTC month or an upgrade; holds already taken can still be confirmed. Filter the candidate pool by `category` (or ordered `categories`, max 10: windows of the first category are tried before the second, and so on), optional `sectionId` (layout section id or name) and optional `zone` (layout zone id or name; seats resolve explicit zone assignment, then their section zone, then the zone outline) before ranking. `tryToPreventOrphanSeats` (default **true**) skips adjacent windows that would leave a single empty seat at either end of the run, falling back to them only when nothing else fits. `ticketTypes` (`{ ticketTypeId: count }`) sets `quantity` to the sum, restricts the search to categories whose ticket catalog offers every requested type, and returns `ticketTypes` (seatId → ticketTypeId) ready to send as `seatTicketTypes` on confirm; events without ticket types reject it. `accessibleSeats` (N) only returns windows containing at least N seats flagged `accessibility.wheelchair` in the published seat structure (409 when no such window exists). `channel` is salesChannel order limits only. Pass **`x-channel-key`** for inventory partitions — do not send the secret in the body. **`hold: false` (default):** suggest only — does not lock. **`hold: true`:** ranks up to 32 candidate windows across the category preferences, locks the first fit in one Lua call each (all-or-nothing per window), then O(cart) PG gates (available/forSale/channel; seats that are not for sale are never picked, not even resale-listed ones of non-propagating season members: those are bought by holding the seats of the listing); on gate failure releases only the locks it added. Requires **Idempotency-Key**, and `userId` unless `holdToken` is given. `holdToken` appends the seats to that existing hold session (same expiry bound; 409 `hold_token_conflict` when the session is expired, foreign, confirming or full). `extraData` is stored on the held seats (requires hold). Returns `hold_token` for confirm. The organizer's booking limits (designer *Max seats per order*) cap `quantity` and, with `holdToken`, the seats already on the token: best-available never picks more than allowed (409 `booking_limit_exceeded` with `limit`, `current`, `requested`). `sections` (max 20 section ids or names, XOR with `sectionId`) ranks across the union of those sections. **API keys / dashboard sessions only:** `channelKeys` (channel secret keys or ids) restricts the pool to public seats plus those channels, `ignoreChannels: true` allows every channel (both replace `x-channel-key`; buyers get 403). `orderId` (with `hold`) is stored on the held seats as `extraData.orderId` and echoed in the response; pass it as `externalOrderId` on confirm. **`status: \"booked\"`** (API keys with the `bookings` scope, or dashboard sessions allowed to change object statuses; buyers get 403) books the best window directly instead of holding it: the same administrative booking as POST /events/{eventId}/actions/book (one SQL transaction under the seat row locks; a seat held by a buyer is never taken; when a ranked window was taken meanwhile the next one is tried). Requires **Idempotency-Key**: the booking order id is derived from it, so a retry returns the same booking. `ticketTypes` are recorded per seat, `extraData` and `orderId` (as `extraData.orderId`) are stored on the booked seats. Response: `status: \"booked\"`, `booked: true`, `bookingOrderId` (cancel with POST /orders/{orderId}/cancel) and `objects` (status, extraData, orderId, ticketType per seat). `status: \"reservedByToken\"` is the same as `hold: true`. **`keepExtraData: true`** (hold or booked) keeps the seats' stored extraData and merges `extraData` / `orderId` on top instead of replacing it.
     # @param post_api_seats_best_available_request [PostApiSeatsBestAvailableRequest] 
     # @param [Hash] opts the optional parameters
     # @option opts [String] :idempotency_key Required on transactional routes. Reuse the same key for every retry of one logical operation; the API replays the stored outcome.
@@ -1006,7 +1006,7 @@ module SeatsChart
     end
 
     # Place a temporary Redis hold (Lua TTL) before payment
-    # JSON body: `eventId`, `seatIds` (1–64 UUIDs, unique; up to the workspace `maxSeatsPerHoldToken` with large group holds), `userId`, optional `holdToken` capability to append seats to an existing session. `userId` is customer metadata, never ownership proof. Renew/append share a two-hour maximum session lifetime. Optional `ticketBuyerId` (opaque partner buyer id) is stored on a new hold token and inherited by its confirmation. `eventId` also accepts the event key. Headers: **x-api-key** (B2B) *or* **Authorization: Bearer** (HS256 JWT); optional **x-tenant-id**; **`Idempotency-Key` is required** (1–255 chars after trim; use a fresh UUID v4 per checkout attempt). Repeats with the same key within ~24h return the cached HTTP status and JSON without re-running the Lua lock. Applies Redis TTL locks (**default 600 s**, overridden by **`SEAT_HOLD_TTL_SEC`**, or by the workspace **hold period** setting — `PATCH /workspace/settings`) with SSE `seat` → **`locked`**; Postgres remains **`available`** until **`POST /api/seats/confirm`** persists **`sold`** via the reservation worker. A hold token holds at most the workspace `maxSeatsPerHoldToken` seats (409 `seat_limit`). **Large group holds (opt-in):** a workspace `maxSeatsPerHoldToken` above 64 (up to 1000, `PATCH /workspace/settings`) lets one request and one hold token hold that many seats of one event; the request is still one atomic lock — every seat of the group is held under the token, or none is (409 `SEAT_LOCKED` when any seat is taken, nothing locked). The sales-channel defaults (web 8, box office 20, partner 64) then step aside; the organizer's booking limits and the workspace cap still apply. Season and multi-event holds keep the 64-lock limit. **Booking limits:** the organizer's *Max seats per order* (designer → Booking limits, stored as `layoutMeta.bookingRules` of the published chart/event layout) caps the seats one hold token holds, appends included, checked in the same atomic call as the locks (parallel appends cannot exceed it); the strictest of the sales-channel default, this limit, the per-buyer limit and `maxSeatsPerHoldToken` wins. Refused with 409 `booking_limit_exceeded` (`limit`, `current` seats already on the token, `requested`, `kind: \"seats\"`). Holds placed before a lower limit was published keep their seats and stay confirmable; they only cannot grow. With ticket buyer validation on, buyer tokens must carry a bound ticket buyer id (403 `ticket_buyer_required` / `ticket_buyer_mismatch`). Seats that are not for sale are refused with 409 `SEAT_NOT_FOR_SALE`, except a seat with an active **resale** listing in a season member whose for-sale configuration does not propagate (`forSalePropagated: false`, e.g. a season-ticket seat its holder resells for one game); the confirmation and the order commit apply the same rule.
+    # JSON body: `eventId`, `seatIds` (1–64 UUIDs, unique; up to the workspace `maxSeatsPerHoldToken` with large group holds), `userId`, optional `holdToken` capability to append seats to an existing session. `userId` is customer metadata, never ownership proof. Renew/append share a two-hour maximum session lifetime. Optional `ticketBuyerId` (opaque partner buyer id) is stored on a new hold token and inherited by its confirmation. `eventId` also accepts the event key. Headers: **x-api-key** (B2B) *or* **Authorization: Bearer** (HS256 JWT); optional **x-tenant-id**; **`Idempotency-Key` is required** (1–255 chars after trim; use a fresh UUID v4 per checkout attempt). Repeats with the same key within ~24h return the cached HTTP status and JSON without re-running the Lua lock. Applies Redis TTL locks (**default 600 s**, overridden by **`SEAT_HOLD_TTL_SEC`**, or by the workspace **hold period** setting — `PATCH /workspace/settings`) with SSE `seat` → **`locked`**; Postgres remains **`available`** until **`POST /api/seats/confirm`** persists **`sold`** via the reservation worker. A hold token holds at most the workspace `maxSeatsPerHoldToken` seats (409 `seat_limit`). **Free (test plan) out of seats:** once the workspace used its 50 seats of the month, new holds (appends included) answer 409 `holds_paused` with a neutral message until the next UTC month or an upgrade; holds already taken can still be confirmed. **Large group holds (opt-in):** a workspace `maxSeatsPerHoldToken` above 64 (up to 1000, `PATCH /workspace/settings`) lets one request and one hold token hold that many seats of one event; the request is still one atomic lock — every seat of the group is held under the token, or none is (409 `SEAT_LOCKED` when any seat is taken, nothing locked). The sales-channel defaults (web 8, box office 20, partner 64) then step aside; the organizer's booking limits and the workspace cap still apply. Season and multi-event holds keep the 64-lock limit. **Booking limits:** the organizer's *Max seats per order* (designer → Booking limits, stored as `layoutMeta.bookingRules` of the published chart/event layout) caps the seats one hold token holds, appends included, checked in the same atomic call as the locks (parallel appends cannot exceed it); the strictest of the sales-channel default, this limit, the per-buyer limit and `maxSeatsPerHoldToken` wins. Refused with 409 `booking_limit_exceeded` (`limit`, `current` seats already on the token, `requested`, `kind: \"seats\"`). Holds placed before a lower limit was published keep their seats and stay confirmable; they only cannot grow. With ticket buyer validation on, buyer tokens must carry a bound ticket buyer id (403 `ticket_buyer_required` / `ticket_buyer_mismatch`). Seats that are not for sale are refused with 409 `SEAT_NOT_FOR_SALE`, except a seat with an active **resale** listing in a season member whose for-sale configuration does not propagate (`forSalePropagated: false`, e.g. a season-ticket seat its holder resells for one game); the confirmation and the order commit apply the same rule.
     # @param idempotency_key [String] Required deduplication key (max 255 chars after trim; UUID v4 recommended). 24h idempotent cache replay in Redis per tenant.
     # @param post_api_seats_reserve_request [PostApiSeatsReserveRequest] 
     # @param [Hash] opts the optional parameters
@@ -1018,7 +1018,7 @@ module SeatsChart
     end
 
     # Place a temporary Redis hold (Lua TTL) before payment
-    # JSON body: `eventId`, `seatIds` (1–64 UUIDs, unique; up to the workspace `maxSeatsPerHoldToken` with large group holds), `userId`, optional `holdToken` capability to append seats to an existing session. `userId` is customer metadata, never ownership proof. Renew/append share a two-hour maximum session lifetime. Optional `ticketBuyerId` (opaque partner buyer id) is stored on a new hold token and inherited by its confirmation. `eventId` also accepts the event key. Headers: **x-api-key** (B2B) *or* **Authorization: Bearer** (HS256 JWT); optional **x-tenant-id**; **`Idempotency-Key` is required** (1–255 chars after trim; use a fresh UUID v4 per checkout attempt). Repeats with the same key within ~24h return the cached HTTP status and JSON without re-running the Lua lock. Applies Redis TTL locks (**default 600 s**, overridden by **`SEAT_HOLD_TTL_SEC`**, or by the workspace **hold period** setting — `PATCH /workspace/settings`) with SSE `seat` → **`locked`**; Postgres remains **`available`** until **`POST /api/seats/confirm`** persists **`sold`** via the reservation worker. A hold token holds at most the workspace `maxSeatsPerHoldToken` seats (409 `seat_limit`). **Large group holds (opt-in):** a workspace `maxSeatsPerHoldToken` above 64 (up to 1000, `PATCH /workspace/settings`) lets one request and one hold token hold that many seats of one event; the request is still one atomic lock — every seat of the group is held under the token, or none is (409 `SEAT_LOCKED` when any seat is taken, nothing locked). The sales-channel defaults (web 8, box office 20, partner 64) then step aside; the organizer's booking limits and the workspace cap still apply. Season and multi-event holds keep the 64-lock limit. **Booking limits:** the organizer's *Max seats per order* (designer → Booking limits, stored as `layoutMeta.bookingRules` of the published chart/event layout) caps the seats one hold token holds, appends included, checked in the same atomic call as the locks (parallel appends cannot exceed it); the strictest of the sales-channel default, this limit, the per-buyer limit and `maxSeatsPerHoldToken` wins. Refused with 409 `booking_limit_exceeded` (`limit`, `current` seats already on the token, `requested`, `kind: \"seats\"`). Holds placed before a lower limit was published keep their seats and stay confirmable; they only cannot grow. With ticket buyer validation on, buyer tokens must carry a bound ticket buyer id (403 `ticket_buyer_required` / `ticket_buyer_mismatch`). Seats that are not for sale are refused with 409 `SEAT_NOT_FOR_SALE`, except a seat with an active **resale** listing in a season member whose for-sale configuration does not propagate (`forSalePropagated: false`, e.g. a season-ticket seat its holder resells for one game); the confirmation and the order commit apply the same rule.
+    # JSON body: `eventId`, `seatIds` (1–64 UUIDs, unique; up to the workspace `maxSeatsPerHoldToken` with large group holds), `userId`, optional `holdToken` capability to append seats to an existing session. `userId` is customer metadata, never ownership proof. Renew/append share a two-hour maximum session lifetime. Optional `ticketBuyerId` (opaque partner buyer id) is stored on a new hold token and inherited by its confirmation. `eventId` also accepts the event key. Headers: **x-api-key** (B2B) *or* **Authorization: Bearer** (HS256 JWT); optional **x-tenant-id**; **`Idempotency-Key` is required** (1–255 chars after trim; use a fresh UUID v4 per checkout attempt). Repeats with the same key within ~24h return the cached HTTP status and JSON without re-running the Lua lock. Applies Redis TTL locks (**default 600 s**, overridden by **`SEAT_HOLD_TTL_SEC`**, or by the workspace **hold period** setting — `PATCH /workspace/settings`) with SSE `seat` → **`locked`**; Postgres remains **`available`** until **`POST /api/seats/confirm`** persists **`sold`** via the reservation worker. A hold token holds at most the workspace `maxSeatsPerHoldToken` seats (409 `seat_limit`). **Free (test plan) out of seats:** once the workspace used its 50 seats of the month, new holds (appends included) answer 409 `holds_paused` with a neutral message until the next UTC month or an upgrade; holds already taken can still be confirmed. **Large group holds (opt-in):** a workspace `maxSeatsPerHoldToken` above 64 (up to 1000, `PATCH /workspace/settings`) lets one request and one hold token hold that many seats of one event; the request is still one atomic lock — every seat of the group is held under the token, or none is (409 `SEAT_LOCKED` when any seat is taken, nothing locked). The sales-channel defaults (web 8, box office 20, partner 64) then step aside; the organizer's booking limits and the workspace cap still apply. Season and multi-event holds keep the 64-lock limit. **Booking limits:** the organizer's *Max seats per order* (designer → Booking limits, stored as `layoutMeta.bookingRules` of the published chart/event layout) caps the seats one hold token holds, appends included, checked in the same atomic call as the locks (parallel appends cannot exceed it); the strictest of the sales-channel default, this limit, the per-buyer limit and `maxSeatsPerHoldToken` wins. Refused with 409 `booking_limit_exceeded` (`limit`, `current` seats already on the token, `requested`, `kind: \"seats\"`). Holds placed before a lower limit was published keep their seats and stay confirmable; they only cannot grow. With ticket buyer validation on, buyer tokens must carry a bound ticket buyer id (403 `ticket_buyer_required` / `ticket_buyer_mismatch`). Seats that are not for sale are refused with 409 `SEAT_NOT_FOR_SALE`, except a seat with an active **resale** listing in a season member whose for-sale configuration does not propagate (`forSalePropagated: false`, e.g. a season-ticket seat its holder resells for one game); the confirmation and the order commit apply the same rule.
     # @param idempotency_key [String] Required deduplication key (max 255 chars after trim; UUID v4 recommended). 24h idempotent cache replay in Redis per tenant.
     # @param post_api_seats_reserve_request [PostApiSeatsReserveRequest] 
     # @param [Hash] opts the optional parameters

data/lib/seatschart/api/usage_api.rb

@@ -87,7 +87,7 @@ module SeatsChart
     end
 
     # Monthly usage: used objects, charts and events
-    # Sandboxes (`isTest: true`) are metered so their usage can be seen, but never billed and never held to plan limits (`limit: null`). `usedObjects.count` is the number of distinct objects booked in the UTC calendar month (seats.io-style billing unit): every seat that became booked counts once per month however often it is retried, released and re-booked; each sold general-admission place counts as one. Holds, test events and replays never count. Map-only renders (`bringYourOwnBackend`) count every object of the rendered chart once per chart and month (`byEvent` entry with the chart id and `mapOnly: true`). `history` has exactly 12 months ending at `month` (zero-filled); `byEvent` lists the top 100 events of the month. `charts`/`events` are current totals against the plan limits. Dashboard JWT (any role) or an API key with the `reports` scope.
+    # Sandboxes (`isTest: true`) are metered so their usage can be seen, but never billed and never held to plan limits (`limit: null`). `usedObjects.count` is the number of distinct objects booked in the UTC calendar month (seats.io-style billing unit): every seat that became booked counts once per month however often it is retried, released and re-booked; each sold general-admission place counts as one. Holds, test events and replays never count. Map-only renders (`bringYourOwnBackend`) count every object of the rendered chart once per chart and month (`byEvent` entry with the chart id and `mapOnly: true`). `history` has exactly 12 months ending at `month` (zero-filled); `byEvent` lists the top 100 events of the month. `charts`/`events` are this workspace's current totals; the plan limits count every production workspace of the billing account together (`account.charts` / `account.events`). `account`: the billing account the workspace belongs to (one plan for all its workspaces) with `ownerEmail`, `isOwner`, `workspaceCount` and the account totals `charts`, `events` and `usedSeats` of the month; `null` in a sandbox or without an account. `seats`: the used seats (the billing unit: one per event, object and month; the same seat sold in two events counts twice) of the billing account in the month — every production workspace of the account, an organizer workspace of a ticketing platform with the platform — with `includedSeats`, `mode` (`overage`: paid plan, extra seats billed per seat; `allowance`: Free, new events and putting events on sale pause above it; `on_demand`: Ultra On-Demand, every seat billed by the SeatsChart team), `overage` { seats, costCents } so far, `projected` (current month at the current pace) and `allowanceExceeded`; `null` in a test workspace. Dashboard JWT (any role) or an API key with the `reports` scope.
     # @param [Hash] opts the optional parameters
     # @option opts [String] :month UTC calendar month `YYYY-MM` (default: current month).
     # @return [nil]
@@ -97,7 +97,7 @@ module SeatsChart
     end
 
     # Monthly usage: used objects, charts and events
-    # Sandboxes (`isTest: true`) are metered so their usage can be seen, but never billed and never held to plan limits (`limit: null`). `usedObjects.count` is the number of distinct objects booked in the UTC calendar month (seats.io-style billing unit): every seat that became booked counts once per month however often it is retried, released and re-booked; each sold general-admission place counts as one. Holds, test events and replays never count. Map-only renders (`bringYourOwnBackend`) count every object of the rendered chart once per chart and month (`byEvent` entry with the chart id and `mapOnly: true`). `history` has exactly 12 months ending at `month` (zero-filled); `byEvent` lists the top 100 events of the month. `charts`/`events` are current totals against the plan limits. Dashboard JWT (any role) or an API key with the `reports` scope.
+    # Sandboxes (`isTest: true`) are metered so their usage can be seen, but never billed and never held to plan limits (`limit: null`). `usedObjects.count` is the number of distinct objects booked in the UTC calendar month (seats.io-style billing unit): every seat that became booked counts once per month however often it is retried, released and re-booked; each sold general-admission place counts as one. Holds, test events and replays never count. Map-only renders (`bringYourOwnBackend`) count every object of the rendered chart once per chart and month (`byEvent` entry with the chart id and `mapOnly: true`). `history` has exactly 12 months ending at `month` (zero-filled); `byEvent` lists the top 100 events of the month. `charts`/`events` are this workspace's current totals; the plan limits count every production workspace of the billing account together (`account.charts` / `account.events`). `account`: the billing account the workspace belongs to (one plan for all its workspaces) with `ownerEmail`, `isOwner`, `workspaceCount` and the account totals `charts`, `events` and `usedSeats` of the month; `null` in a sandbox or without an account. `seats`: the used seats (the billing unit: one per event, object and month; the same seat sold in two events counts twice) of the billing account in the month — every production workspace of the account, an organizer workspace of a ticketing platform with the platform — with `includedSeats`, `mode` (`overage`: paid plan, extra seats billed per seat; `allowance`: Free, new events and putting events on sale pause above it; `on_demand`: Ultra On-Demand, every seat billed by the SeatsChart team), `overage` { seats, costCents } so far, `projected` (current month at the current pace) and `allowanceExceeded`; `null` in a test workspace. Dashboard JWT (any role) or an API key with the `reports` scope.
     # @param [Hash] opts the optional parameters
     # @option opts [String] :month UTC calendar month `YYYY-MM` (default: current month).
     # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
@@ -478,7 +478,7 @@ module SeatsChart
     end
 
     # Monthly used objects across my workspaces (admin view)
-    # Every workspace the caller administers (role admin), with its plan, status and used objects of the month against the plan limit (`null` for sandboxes, which are metered but never billed), plus the total of the production workspaces (`usedObjects`) and, separately, of the sandboxes (`sandboxUsedObjects`). Dashboard session, or a **workspace admin API key** (the admin it is bound to); other API keys: 403 `ERR_PARTNER_SCOPE`. One grouped read of the metering table.
+    # Every workspace the caller administers (role admin), with its plan, status and used objects of the month against the plan limit (`null` for sandboxes, which are metered but never billed), plus the total of the production workspaces (`usedObjects`) and, separately, of the sandboxes (`sandboxUsedObjects`). Each item names its billing account (`billingOwnerUserId`); `accounts` lists those accounts (the caller's own first) with the owner, the plan and the totals of every production workspace of the account (`workspaceCount`, `charts`, `events`, `usedObjects` against the plan's included seats), since one plan covers them all. Dashboard session, or a **workspace admin API key** (the admin it is bound to); other API keys: 403 `ERR_PARTNER_SCOPE`. One grouped read of the metering table.
     # @param [Hash] opts the optional parameters
     # @option opts [String] :month UTC calendar month &#x60;YYYY-MM&#x60; (default: current month).
     # @return [nil]
@@ -488,7 +488,7 @@ module SeatsChart
     end
 
     # Monthly used objects across my workspaces (admin view)
-    # Every workspace the caller administers (role admin), with its plan, status and used objects of the month against the plan limit (&#x60;null&#x60; for sandboxes, which are metered but never billed), plus the total of the production workspaces (&#x60;usedObjects&#x60;) and, separately, of the sandboxes (&#x60;sandboxUsedObjects&#x60;). Dashboard session, or a **workspace admin API key** (the admin it is bound to); other API keys: 403 &#x60;ERR_PARTNER_SCOPE&#x60;. One grouped read of the metering table.
+    # Every workspace the caller administers (role admin), with its plan, status and used objects of the month against the plan limit (&#x60;null&#x60; for sandboxes, which are metered but never billed), plus the total of the production workspaces (&#x60;usedObjects&#x60;) and, separately, of the sandboxes (&#x60;sandboxUsedObjects&#x60;). Each item names its billing account (&#x60;billingOwnerUserId&#x60;); &#x60;accounts&#x60; lists those accounts (the caller&#39;s own first) with the owner, the plan and the totals of every production workspace of the account (&#x60;workspaceCount&#x60;, &#x60;charts&#x60;, &#x60;events&#x60;, &#x60;usedObjects&#x60; against the plan&#39;s included seats), since one plan covers them all. Dashboard session, or a **workspace admin API key** (the admin it is bound to); other API keys: 403 &#x60;ERR_PARTNER_SCOPE&#x60;. One grouped read of the metering table.
     # @param [Hash] opts the optional parameters
     # @option opts [String] :month UTC calendar month &#x60;YYYY-MM&#x60; (default: current month).
     # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers