Search Time Slots

Browse-oriented endpoint for calendar UIs: returns every time slot for an item across a date range, with optional indicative pricing and current capacity. Designed for use cases like a 30-day calendar UI or a realtime capacity check across a date window. This endpoint is **not** a replacement for [`getCapacity`](./getCapacity) — that endpoint stays as the single-date, at-checkout call carrying `customerNumber` for personalized pricing and authoritative capacity validation. Prices here are **indicative** — `customerNumber` and `quantity` aren't accepted, so customer-specific pricing, price ladders, and quantity discounts are not applied. Slot-level **dynamic pricing is** applied and surfaces as `priceDelta` on each time slot (see "Per-unit math" below for how to combine it with `basePrice`). Capacity is accurate at the moment of the response but drifts as bookings come in. Re-validate at the slot the customer actually picks. ## Date-range cap The range cap is **62 days** (`toDate - fromDate + 1`). Larger ranges return `400`. ## Times are admission-local All `*Date` / `*Time` fields are local at the admission. **No timezone offset is attached.** Do not parse the time fields as UTC. `endDate` can differ from `startDate` for slots that cross midnight. ## Per-unit math Both `basePrice` (in `datePrices`) and `priceDelta` (on each time slot) are **per unit**. For a picked slot, the per-unit price is `basePrice + priceDelta`. The item's contribution to a multi-ticket package is `items[].quantity × (basePrice + priceDelta)`. For well-configured items `quantity` is typically `1`, but the multiplier still applies when present. ## Capacity semantics When `withCapacity=true`, each time slot carries a `capacityControl` field — one of `none`, `sales`, `admitted`, or `full`. Branch on it: - `none` — capacity is not tracked for this slot. `remainingCapacity` is **omitted**. Render as "Available" / "Unlimited" — there is no number to display. - Any other value — `remainingCapacity` is present and is the actual count. `0` means sold out. The number's semantics differ by mode (e.g. `sales` counts initial sales, `admitted` counts admitted entries) — interpret with `capacityControl` for accuracy across modes. `capacityControl` is **per slot, not per admission** — the same admission may have different effective modes on different slots. ## v1 inclusion scope Only `mandatory` admissions are emitted in v1. Opt-in and opt-out admissions (`optionalAndSelected`, `optionalNotSelected`) and their addon-experience pricing are out of scope for v1. ## Decomposition The input item is resolved into one or more ticket items, and each ticket item carries one or more admissions: - **Input item → ticket items.** For a single ticket item, `items[]` has exactly one entry. For a package (an item with an item add-on configured), `items[]` has one entry per underlying ticket item in the add-on; non-ticket items in the add-on (souvenirs, coupons, etc.) are filtered out. - **Ticket item → admissions.** Each ticket item's `admissions[]` lists every admission the ticket grants access to. A simple ticket grants one; a combo ticket grants several. See "v1 inclusion scope" for which admissions are emitted today. ## What this endpoint does not do - No `customerNumber` — use [`getCapacity`](./getCapacity) for personalized pricing. - No `quantity` — defaults to 1; the caller multiplies by `items[].quantity`. - No rolled-up `packagePrice` / `packageAvailable` — the caller composes from per-row data. - No timezone offsets on time fields (see above). - Slots whose sales window has ended are not filtered here — that's a [`getCapacity`](./getCapacity) concern at point-of-purchase. Cancelled slots and slots not marked visible-on-web are excluded. Consumers can pass `scheduleNumber` from a `timeSlots[]` row directly to [`createReservation`](./createReservation) and to [`getCapacity`](./getCapacity) — same field name, same value, no translation.