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 thex-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
Read the rest of the response
The field-by-field reference for a slate is in Suggestions:- Response fields:
primarySlate,alternates,partial,cadenceAlternativesand the rest of the envelope. - Slate and slot fields:
every field of a slate, its cadence provenance, and each entry in
slots[]. - How well a slate matches:
matchScoreandmatchComponents. Don’t re-sort the slates you receive bymatchScore. - How often a plan runs:
cadenceSummary. Renderpeak, notaverage. - Why a slate departs from your request:
matchNotes, with the nine codes and a hint about starting later:advice.
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
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
lookAheadStartDate, so a Z suffix would produce a garbage
offset and silently wrong results — the API rejects it outright instead:
-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’screditCount, 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:
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.
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 empty422 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.
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 a200 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:
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:
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.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:
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 isprimarySlate, andcadenceAlternativescarries the denser options alongside it. - When the requested cadence can’t be met but a relaxed one can:
status: "ALTERNATIVE_CADENCE",primarySlateisnull, and the answer iscadenceAlternatives[0]— already ordered closest-first, with the frequency target ranked ahead of raw cadence distance. This is a200, not a failure. A client that reads onlyprimarySlateconcludes 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 onprimarySlatealone” point. - Take
cadenceAlternatives[0]rather than re-sorting bymatchScore— see the warning in Suggestions: a three-a-week plan ties a two-a-week one against a target of2, 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:
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:
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.
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-DDstring 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 flat422 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:
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:
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
BothslateId 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).
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
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.