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 on `timeSlots[]` are in the admission's local wall clock — no timezone offset is attached to the slot fields. Do not parse them as UTC, and do not compare them to the consumer's own clock. Each admission's `admissions[].admissionLocalTime` carries the admission's wall clock at response time (with offset) — compare slot times against that as the reference. Different admissions in one response may sit in different time zones. `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**. Reconstruct the charged price by combining them — what to combine depends on the component shape: - **Single-admission ticket component** — pick a slot, then per-unit price is `basePrice` (for that component and date) `+` the chosen slot's `priceDelta`. - **Multi-admission ticket component** — `basePrice` is carried **once**, on the default admission's `datePrices` row. A non-default admission's `priceDelta` is its **incremental** contribution, not a standalone price — do not add the base per admission. Per-unit price = `basePrice` (default admission's row, for the date) `+ Σ` chosen slot's `priceDelta` across the admissions the customer is buying. - **Non-admission component** (coupon, fee, etc.) — per-unit price is the `basePrice` from its `datePrices` row for the date. No `priceDelta` applies; the component doesn't appear in `timeSlots[]`. Multiply by `items[].quantity` to get each component's contribution to the package total, then sum across components. This matches what the actual charged price will be: the per-slot dynamic adjustment is computed against the price-list price for the date, and any package-level discount is applied last. **What `basePrice` and `priceDelta` carry:** - `basePrice` reflects the price-list price for the date (so it tracks scheduled price-list changes, e.g. seasonal pricing) with any package-level discount applied. It does **not** include the per-slot dynamic adjustment. - `priceDelta` carries the per-slot dynamic rule (fixed, relative, or percentage), with the same package-level discount applied so `basePrice + priceDelta` reconciles cleanly to the discounted total. ## 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. ## Closed slots A slot carries `closed: true` when a configured calendar closes the slot's date. Any calendar layer — admission calendars, schedule calendars, or the ticket base calendars on the BOM item and admission — can trigger this. The response merges them into the single flag; the specific closing calendar is not identified in the payload. `closed` is a calendar signal, not a bookability signal. An absent `closed` means the date is open per the calendars — it does not mean the slot can be reserved. For bookability (sold-out, sales window, elapsed), use [`getCapacity`](./getCapacity) at point-of-purchase. ## 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 components, and each ticket component carries one or more admissions: - **Input item → components.** For a single ticket item, `items[]` has exactly one entry. For a package, `items[]` has one entry per underlying item in the package. Components are one of two kinds: - **Ticket components** — items configured as tickets. They appear in `items[]` with at least one entry in `admissions[]`, in `datePrices[]` with the default admission's code, and in `timeSlots[]`. - **Non-admission components** — items like coupons or fees that are part of the package but don't have admissions. They appear in `items[]` with an **empty** `admissions` array, and in `datePrices[]` with `admissionCode: ""` (blank). They never appear in `timeSlots[]` — there's no schedule to attach to. - **Ticket component → admissions.** Each ticket component'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. - Elapsed slots are not filtered — a `fromDate` in the past returns past slots. Compare each slot's `startDate`/`startTime` against the matching admission's `admissionLocalTime` to detect elapsed slots. Consumers can pass `scheduleNumber` from a `timeSlots[]` row directly to [`createReservation`](./createReservation) and to [`getCapacity`](./getCapacity) — same field name, same value, no translation.