Skip to main content
This is the deep-dive companion to Create a package booking with a slate. That guide covers the primary flow — build a slate, create an order, book it by slateId — end to end. This page goes underneath it: what the five availability endpoints are for, how to read a slate response, the cadence rules that shape it, what happens when a supplier can’t meet those rules, and the two advanced booking paths that exist alongside book-by-slateId. Every field of a slate response, slate and slot is documented in Suggestions. It builds on The booking engine model — read the Slates section first if you haven’t.

The availability engine

Five endpoints make up the availability engine, all authenticated with the x-api-key header (see the table below for exact paths). They’re layers of the same clustering engine, from lowest to highest level:
/search, /time-slots and /suppliers are documented in full in the Availability resource reference — request fields, the recurring-search variant, and response envelopes. This guide focuses on /package-slate, since it’s the one with package-specific anatomy and the two advanced booking paths below.How breaks in a day, drives with traffic, a service’s bufferBeforeStartMinutes, and start and end of day locations shape the times on offer is in How offered times are worked out.

Anatomy of a slate

POST /availability/package-slate takes a packageId (the session count, service, and offering are derived from it), a location, a timezone, and a cadence (lookAheadStartDate + rrule). To plan what is left on a credit, send its orderId and orderItemId instead of packageId. See Book the sessions left on a credit. The response is a PackageSlateResponse:
(slots[] abridged to [] here — see Create a package booking for a fully populated example, and Slate and slot fields for its shape. alternates is shown empty for brevity too — under the default supplierPolicy of SAME_SUPPLIER it carries this same supplier’s other bookable schedules.)

Status values

The endpoint returns 422 only when primarySlate, partial and cadenceAlternatives are all empty — nothing bookable at all. The code is then the status (NO_COMPLETE_SLATE or NO_AVAILABILITY), not a 200 with an empty body.A non-empty cadenceAlternatives is bookable output, so it makes the response a 200 (ALTERNATIVE_CADENCE) even with primarySlate: null. Don’t branch on primarySlate alone once you’ve opted into relaxation.

Read the rest of the response

The field-by-field reference for a slate is in Suggestions:

Cadence rules: rrule and lookAheadStartDate

package-slate derives its whole session plan from two request-shape guarded fields. Both are enforced at validation time (a 400 before the engine ever runs), not just documented convention.

rrule needs a bounded, positive COUNT

An unbounded rrule almost never returns anything bookable — the engine needs a specific number of occurrences to try to fill, not an open-ended pattern. Omitting COUNT (or giving COUNT=0) fails validation:
The message is prefixed with the offending field name (rrule: …) — the validation layer prepends the field path to every schema error.

lookAheadStartDate needs a numeric offset, not Z

The slate builder derives the request’s UTC offset from the last six characters of lookAheadStartDate, so a Z suffix would produce a garbage offset and silently wrong results — the API rejects it outright instead:
Make the offset the zone’s real offset for that date — Toronto is -04:00 in summer but -05:00 in winter. The timezone alongside it must be an IANA identifier (America/Toronto, never EST); see Timezones.
This guard is specific to the two package endpoints. Recurring POST …/availability/search accepts a Z instant since September 10, 2026.

The 120-day look-ahead ceiling

You don’t have to compute the look-ahead window yourself — by default it’s derived from your cadence and the package’s creditCount, so the engine searches exactly as far ahead as it needs to fit every session. That derived window is capped at 120 days. That ceiling is wide enough for the ordinary weekly product. A weekly 10-session package (FREQ=WEEKLY;BYDAY=MO;COUNT=10) spans about 70 days — comfortably inside the window — so it plans and books normally. Weekly 12-packs (~84 days) and biweekly 5-packs (~70 days) fit too. What happens when the cadence is too sparse to fit all of a package’s sessions within 120 days depends on whether you asked for cadence flexibility. The two behaviours are genuinely different code paths: The clamp is not a loosened guardrail — it’s the whole point of relaxation. A denser cadence needs a shorter window, so the over-window case is exactly the one the relaxation ladder can answer: Monday-only COUNT=20 needs 134 days ✗, but the same 20 sessions twice a week need only 70 ✓. Returning early would short-circuit the feature before it ever got to try. For example, a package with creditCount: 20 requested with a Monday-only cadence (FREQ=WEEKLY;BYDAY=MO;COUNT=20) needs about 20 weeks (134 days including the inclusive end boundary) to fit all 20 sessions — over the cap. On the default NONE path nothing is bookable, so this comes back as a 422 in the standard error envelope (the reason becomes message and the status becomes code), not a 200 with a slate body:
Send the same request with cadenceFlexibility: "FALLBACK" and you get a 200 instead: the window clamps to 120 days, the engine runs, and any complete denser plan the supplier can actually fill comes back in cadenceAlternatives with status: "ALTERNATIVE_CADENCE". If even the relaxed cadences fail, it’s a 422 again — the clamp buys the engine a chance to answer, it doesn’t manufacture availability. Compare that to the working example from Create a package booking: an 8-session package with FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;COUNT=8 fits 8 sessions into under two weeks (five eligible weekdays per week), well inside the cap.
If you need a window wider than the derived default, pass lookAheadDays or endDate explicitly. Doing so skips the derivation entirely — you own the window. Neither the 120-day cap nor the relaxation padding is applied to a window you sized yourself: the 120 is a ceiling on the window the API derives from your cadence, not a ceiling the engine enforces on a window you state outright. So an explicit lookAheadDays: 200 really does search 200 days.The trade is that nothing sanity-checks it for you. Too small and the cadence can’t fit; too large and you pay for pool the engine has to build. See the warning below for what an explicit window costs a relaxation request specifically.
An explicit lookAheadDays or endDate also opts you out of the padding that cadence relaxation relies on. When the window is derived, a relaxation request widens it by a few days so a weekday substitution — which can need a slightly longer span than the cadence you asked for — has room to land. Size the window yourself and that padding is gone, so a substituted cadence needing a handful more days is silently dropped from cadenceAlternatives. If you’re combining cadenceFlexibility with an explicit window, budget a week of headroom, or let the derivation do it for you.

Cadence relaxation

A supplier who works every weekday still can’t give you eight Fridays if their schedule only runs four weeks. Historically that returned an empty 422 and left you with nothing to show — the single biggest complaint against the booking engine. Now you can ask the engine to answer with a denser, supplier-feasible cadence instead: complete N-session plans that fit the supplier’s real availability but don’t follow the rrule you asked for. They arrive in cadenceAlternatives, each with a directly bookable slateId.
This is strictly opt-in, and the opt-in is absolute. A request that sets neither cadenceFlexibility nor guaranteeSlate behaves exactly as it did before this feature existed — same slates, same statuses, same 422s. cadenceFlexibility defaults to NONE, cadenceAlternatives comes back empty, and ALTERNATIVE_CADENCE is unreachable. You cannot be broken by this change without asking for it.

Request fields

All seven are optional, and all seven exist on both /availability/package-slate and /availability/package-options: Two further optional fields — daysOfWeek and excludeDates — also exist on both endpoints. They aren’t relaxation controls; they constrain which calendar days any plan may use, relaxed or not. See Schedule preferences.

What comes back

When relaxation produces something and the requested cadence didn’t, the response is a 200 with status: "ALTERNATIVE_CADENCE", primarySlate: null, and a populated cadenceAlternatives sorted closest-first by cadenceDistance. Every entry is a normal slate: book it by slateId, hold it by slateId, transcribe its slots[] — all three paths in this guide work identically on an alternative.

Worked example

A supplier works Mon–Fri, 09:00–17:00, America/Toronto, on a schedule that runs 2026-07-06 → 2026-08-03 — about four weeks. The client wants an 8-session package on Fridays. Eight Fridays would run to late August; the schedule ends after the fourth. So the requested cadence is unfillable even though the supplier is demonstrably available. Send this body to POST /availability/package-slate:
With cadenceFlexibility omitted (or "NONE"), that request is a 422 NO_COMPLETE_SLATE — unchanged, and still the default. With "FALLBACK", the same request returns a 200, and the response carries a complete eight-session plan on Mondays and Fridays:
(Abridged: suggestionRequestId, resolvableUntil and the remaining two alternatives are omitted, and slots[] is collapsed as elsewhere on this page.) matchScore is 0.5, not 1: DAYS_ADDED is a frequency change the request didn’t authorise, so cadence scores 0 and drags the mean down from the startDate component’s 1. The eight sessions land on Jul 6, 10, 13, 17, 20, 24, 27 and 31 — all inside the supplier’s schedule, where eight Fridays would have needed until late August. cadenceRelaxation is DAYS_ADDED because Friday was kept and one weekday was added; cadenceDistance: 2 ranks it as the closest answer available. cadenceSummary reads that same plan back as a cadence: requested: 1, because the rrule you sent named one weekday, against a peak of 2 — the number to put in front of a client. Here the plan runs at exactly two a week in all four of its weeks, so average matches peak; the two only part company when a week comes up short.
Monday is chosen, not Wednesday or Thursday, because when the engine adds a weekday it maximises the spacing between sessions. {MO, FR} leaves gaps of 4 and 3 days; {TH, FR} would leave 1 and 6. Sessions spread evenly across the week beat sessions bunched against the day you asked for.
Here the default maxCadenceAlternatives: 3 means three plans come back — MO,FR first, then progressively denser ones. Render them as a choice (“we can’t do 8 Fridays, but we can do 8 sessions on Mondays and Fridays”) rather than picking one silently.

Asking for a frequency: “twice a week, any day”

A frequency picker collects “twice a week” with no weekday preference. rrule can’t express that on its own — it names specific weekdays — and daysOfWeek is a hard filter, so naming days there would rule every other day out. Send sessionsPerWeek alongside a starting-point rrule instead. Here’s a complete body for POST /availability/package-slate: rrule is required on this endpoint, so the two weekdays in it are a starting point, not a constraint — sessionsPerWeek states the real target, and allowWeekdaySubstitution (default true) lets the engine move the days to hit it:
Omit daysOfWeek entirely. Sending it would make MO,TH a hard filter and, on top of that, withdraw the cadence component’s substitution exemption (see How well a slate matches). On /availability/package-options, rrule is optional; omit it there and the cadence is synthesised per package from its credit count, with sessionsPerWeek still steering. sessionsPerWeek is always scored — matchComponents.sessionsPerWeek comes back on any slate — but it only steers which slates get built when cadence relaxation actually runs. That means cadenceFlexibility: "ALWAYS", or "FALLBACK" once the requested cadence yields nothing, or guaranteeSlate: true (which promotes NONE to FALLBACK). On the default "NONE", the rrule fixes the schedule completely, and the target is scored but changes nothing about which slates come back. Where to read the answer — and the trap that pairs with the point above:
  • With "ALWAYS" and a fillable requested cadence: status: "OK", the answer is primarySlate, and cadenceAlternatives carries the denser options alongside it.
  • When the requested cadence can’t be met but a relaxed one can: status: "ALTERNATIVE_CADENCE", primarySlate is null, and the answer is cadenceAlternatives[0] — already ordered closest-first, with the frequency target ranked ahead of raw cadence distance. This is a 200, not a failure. A client that reads only primarySlate concludes there’s no availability when a bookable plan is sitting right there — see the warning under Status values, which already makes the “don’t branch on primarySlate alone” point.
  • Take cadenceAlternatives[0] rather than re-sorting by matchScore — see the warning in Suggestions: a three-a-week plan ties a two-a-week one against a target of 2, so only the order tells them apart.

guaranteeSlate and the direct fill

When every relaxed cadence also fails — the supplier works no Fridays at all, say, and you’ve set allowWeekdaySubstitution: false so Friday can never be dropped — guaranteeSlate: true adds one last floor: a direct fill. All N sessions are picked straight from the supplier’s real openings, one per day, at the most consistent start time available, following no recurrence rule at all. Direct-fill slates are recognisable by two fields:
guaranteeSlate guarantees flexibility of cadence, not of capacity. The name promises more than it delivers if you read it quickly. A supplier who simply doesn’t have N open days still yields no complete plan — there is no cadence clever enough to invent time that isn’t there. When that happens the under-filled plan is surfaced (or not) through partial, governed by the project’s suggestionConfig.allowPartialPackages setting, exactly as it is today. guaranteeSlate does not override that setting, and it is not a guarantee that you always get a slate.

Schedule preferences: daysOfWeek and excludeDates

package-slate and package-options both also take two fields that narrow which calendar days a session is allowed to land on, on top of the cadence itself.

daysOfWeek is a hard filter, not a preference

daysOfWeek is an allow-list of weekdays sessions may fall on, using the convention 0 = Sunday … 6 = Saturday:
It’s enforced before the planner ever looks at the supplier’s availability: a weekday you leave out is removed from the pool the engine plans against, not filtered out of a result afterward. That has one consequence worth stating plainly — cadence relaxation cannot reintroduce a day daysOfWeek excludes. Every fallback cadence cadenceFlexibility can produce, including the direct fill guaranteeSlate reaches, still plans only inside the allowed weekdays. A UI’s “No Sundays” choice stays honoured even when the planner has to work harder to fill the package.
daysOfWeek is an allow-list, not a block-list. If your UI collects exceptions the other way around — “No Sun / No Mon” chips a client toggles on to exclude those days — you must invert the selection before calling the API: send the days that remain ([2, 3, 4, 5, 6]), not the two the client excluded. Sending the excluded days directly restricts the plan to almost nothing instead of almost everything — the obvious integration bug here.
Omit daysOfWeek entirely to allow any day.
Same field name, opposite behaviour on /availability/suppliers. This hard-filter behaviour is specific to package-slate and package-options. On POST /availability/suppliers, daysOfWeek is a ranking preference, not a filter — a weekday you leave out is never removed from a supplier’s slots, it only lowers that supplier’s availabilityMatch score. Check which endpoint you’re calling before you carry an integration’s daysOfWeek handling over from one to the other.

excludeDates blocks specific local dates

excludeDates is a list of individual local calendar dates that must not carry a session:
  • Dates are LOCAL, matching how the planner buckets slots — a YYYY-MM-DD string matched against each slot’s own local calendar date as the planner buckets it, not a UTC instant.
  • Each date is passed individually — there is no range form. A five-day trip is five entries in the array, not a { from, to } pair.
  • Maximum 90 dates per request.

The synergy: a blackout doesn’t have to mean a refusal

Blacking out enough dates to make the exact requested cadence unfillable used to mean the request came back a flat 422 NO_COMPLETE_SLATE — even if the supplier had plenty of other open time. With cadenceFlexibility opted in, the same blackout can now produce a relaxed-cadence plan instead of a refusal. Take the same supplier as the worked example above — Monday–Friday, 09:00–17:00, in America/Toronto (-04:00 in July), on a schedule that runs 2026-07-06 (a Monday) through 2026-08-03. This time request eight sessions, twice a week, on Mondays and Fridays:
Without any exclusions, that cadence fills cleanly — eight sessions on Jul 6, 10, 13, 17, 20, 24, 27, and 31. Now black out the third week’s Monday and Friday:
That removes 2 of the 8 occurrences the exact cadence needs. The rest of the ~4-week schedule has only 7 more Monday/Friday slots to draw from (4 Mondays + 3 Fridays — the next Friday, Aug 7, falls after the schedule ends), one short of the 8 requested. No occurrence set of the exact MO,FR cadence can complete, from any start date — every prior version of this endpoint would 422 here. With cadenceFlexibility: "FALLBACK" set, the response instead comes back:
(cadenceAlternatives[0].slots abridged to [] here, the same convention as Anatomy of a slate above. cadenceDistance — present on a real response here, since it’s stamped whenever relaxation was requested — and cadenceSummary, which is present on every response whether relaxation was requested or not, are left out too: their exact numbers depend on which admissible cadence the engine actually picks, which the underlying test doesn’t pin down. Every other field is real: reason always carries that exact string whenever status is ALTERNATIVE_CADENCE; suggestionRequestId and resolvableUntil are present because persist defaults to true; requestedCadence is present because cadenceFlexibility was set to anything other than NONE — it echoes rrule verbatim.) matchScore is 0.5 for the same reason as the worked example above: DAYS_ADDED scores cadence at 0, averaged with startDate’s 1. primarySlate is null — the exact requested cadence is genuinely unfillable — but cadenceAlternatives carries at least one COMPLETE plan (all 8 sessions, none of them on an excluded date), sorted closest-first, at a denser cadence that finishes before ever reaching the blackout week. (The exact alternate depends on the supplier’s real openings — adding Tuesday and Wednesday, shown above, is one admissible rung that reaches 8 sessions by day 12, well ahead of the July 20 blackout.) A request that used to be a dead end now returns a workable, shifted plan.
daysOfWeek and excludeDates are accepted by package-options too, with identical semantics — it plans every ACTIVE package the same way package-slate plans one.

Path A: book explicit sessions (transcribe)

The primary path — passing { orderItemId, idempotencyKey, slateId } to POST .../package-bookings — is what Create a package booking walks through, and it’s the one to reach for by default: the server re-resolves every session itself. Path A is the fallback for when you need to alter or filter individual sessions before booking (for example, dropping one session from an 8-session slate, or swapping in a client-chosen alternate time you resolved separately). Instead of slateId, you build a sessions[] array yourself by copying each slot from the slate response:
Copy each slot verbatim — do not re-derive locations. A TRAVEL_ZONE slot’s locationId is the supplier’s resolved travel zone, computed by the slate engine specifically for that supplier and location. Recomputing it yourself (e.g. re-resolving from raw lat/lng) can silently select the wrong zone and mis-place the booking by a meaningful distance. Take the slot fields as-is; only omit or reorder whole sessions, never recompute their contents.The one field to drop is latitude/longitude on a PHYSICAL slot. The slot carries the Location’s coordinates, but a PHYSICAL session that sends them is a 400 with PHYSICAL bookings derive coordinates from the Location — do not pass latitude/longitude, and nothing is booked.
slotId, sessionIndex, travelTimeMins, capacity, and the deprecated reservationStatus are not part of a session entry — they’re slate metadata, not booking input. Only the fields listed above go into sessions[]. Provide exactly one of sessions, slateId, or slotIds on POST .../package-bookings — sending more than one (or none) is a 400 VALIDATION_ERROR.

Path B: hold, then convert

Both slateId and Path A book immediately. If you need to hold the sessions while the client pays — a timed checkout — don’t book at all: hold the slate, take payment, then convert the hold into bookings. Holds are no longer a package-only concept, and they no longer live under /suggestions. A hold is a standalone claim on supplier time (POST /v1/projects/{projectId}/holds), and it takes exactly one of intervals (explicit supplier time — this is how you hold a single session, with no package or slate anywhere), slateId (every slot of the slate you just built), or slotIds (a cherry-picked subset). Convert is a single endpoint for both shapes. The whole lifecycle — hold, heartbeat, convert, release, and the SLOT_HELD error you get if you try to book held time directly — is covered in Hold slots during checkout. Holding by slateId / slotIds takes no location fields: the slate’s persisted slots already carry bookingTz, locationType, locationId, coordinates and address, and the hold copies them onto the reservation — the same reason book-by-slateId needs no address. The explicit intervals form is the one that must supply them itself (bookingTz and locationType are required on every interval).
A live hold blocks the time it claims: the slot stops being returned by availability search, and a direct POST .../package-bookings over it fails with 409 SLOT_HELD — even when the hold is your own. If you hold, you convert. See Concurrency.

Reference

Endpoints used in this guide

For suggestion requests, slates and slots as objects, and the 24-hour window they stay usable in, see Suggestions. To let a client move one session of a slate before you hold or book it, see Let clients adjust a proposed slate. For the hold object, see Holds.

Configuration

Errors and edge cases

The granular stale codes above (SLATE_NOT_FOUND, SLOT_NOT_FOUND, SUGGESTION_EXPIRED) are returned verbatim only by POST /holds. At booking time — POST .../package-bookings by slateId/slotIds — every one of these same stale conditions is collapsed to a single code: "SLOT_NO_LONGER_BOOKABLE" (the message still names the specific cause). Branch on the distinct codes only when you’re calling the holds endpoint; for direct booking, branch on SLOT_NO_LONGER_BOOKABLE alone.
See Errors for the full envelope and code list, Concurrency for supplier-time conflicts, and Create a package booking for the errors specific to the order/order-item side of booking (expired packages, insufficient quantity, and so on) — convert shares that same booking path and can return the same set.