This page is the reference for these objects, including every field of a
slate and its slots. For how a slate is planned, see
Availability and slates.
Where suggestions come from
Two routes plan slates:POST /v1/projects/{projectId}/availability/package-slateplans one package, or the sessions left on an order item. See Anatomy of a slate.POST /v1/projects/{projectId}/availability/package-optionsplans everyACTIVEpackage of a service in one call. See Show a package storefront.
persist: false. A
stored suggestion comes back with a suggestionRequestId, and its slates and
slots can be held or booked by id. A slate you didn’t store can only be
shown.
Suggestions expire after 24 hours
A stored slate and its slots stay usable by id for 24 hours from the planning call. The response’sresolvableUntil says when.
After that, every route that takes a slateId or slotId treats it as stale.
Plan a new slate rather than retrying the old id.
What you can do with a slate
Each of these routes re-checks the time when you call it. A slot that was free
when it was planned may have been taken since.
Anatomy of a slate and a slot
POST /availability/package-slate returns a PackageSlateResponse. Each
entry of POST /availability/package-options carries slates of the same
shape. For an
example response, and how to branch on its status, see
Anatomy of a slate and
Status values.
Response fields
Two schedules from the same supplier count as different options only when they run on
different weekdays or start at least 30 minutes apart — a supplier offering both 09:00
and 09:20 contributes one option, not two.
Slate and slot fields
Each slate (primarySlate, entries in alternates, entries in
cadenceAlternatives, and partial) has the same shape:
Slates additionally carry cadence provenance — a record of how the plan’s
cadence relates to the one you asked for. These fields are absent unless the
request opted into cadence relaxation:
Cadence provenance is provenance: it records how the slate was generated.
It is not re-validated if a session is later rescheduled, so a booked plan can
drift from its own
cadenceRrule.cadenceSummary is deliberately
not in this table. It’s measured from the slate’s own sessions rather than
recorded from the request, so it isn’t gated on relaxation and it isn’t
provenance — it arrives on every path and is recomputed on every rebuild.slots[]:
How well a slate matches: matchScore and matchComponents
matchScore is the arithmetic mean of the components present in
matchComponents, each itself a 0–1 ratio. There’s no rounding.
Each component is a 0–1 ratio measured against what you asked for. Most
are measured over this slate’s own sessions; startDate is measured
against the window instead, and cadence is binary rather than a ratio at
all:
excludeDates is never a component — it’s a hard filter, so it could only
ever score 1, and including it would just dilute the mean. A component you
didn’t ask about is simply left out of matchComponents, and the score is
the mean of whatever remains.
The cadence component, so you can predict its value:
1when the slate runs at therruleyou requested.1also when the only departure was a weekday substitution you authorised —cadenceRelaxationofDAYS_SUBSTITUTEDorALL_WORKING_DAYS, withallowWeekdaySubstitution: true(the default) and nodaysOfWeeksent. Naming your weekdays withdraws that authorisation, because it says the weekdays are the point.0when the cadence changed in a way you didn’t authorise — including every change to how often sessions occur (INTERVAL_TIGHTENED,DAYS_ADDED). Allowing weekday substitution doesn’t authorise a frequency change.- Absent, not
0, on a slate that follows no cadence at all: aDIRECT_FILLslate and aPARTIALslate are both greedy fills that never consult yourrrule, so the question is unanswerable rather than answered zero. Absent too when you sent norrule.
matchScore: 1
with matchComponents: {}. Read matchComponents, not the score, to tell
“perfect match” from “nothing asked”.
A fresh call to /availability/package-slate or /availability/package-options
always carries matchComponents, even when it’s empty. The key is absent
entirely only on a slate resolved from a booking made before this shipped —
the book-by-slateId, 409-stale-rebuild, and reschedule paths read an
existing row rather than running a fresh match, so that row’s matchScore: 1
comes back with no matchComponents at all. Treat a missing key as “no data
recorded”, a third case alongside “perfect match” and “nothing asked”.
How often a plan runs: cadenceSummary
cadenceSummary answers the one question a booking UI has to render — “how
often is this plan?” — and it answers it week by week rather than as a single
rate. It’s on every slate holding at least one session, on every request
path, including the default cadenceFlexibility: "NONE". It’s absent only for
a slate with no sessions at all, which has no cadence to describe.
Render
peak, not average. The nine sessions above run 1 / 0 / 4 / 4 —
the supplier has a week off in the middle of the plan. Those four weeks
average 2.25, and not one week in the plan runs at 2.25. An average is the
one number that describes none of the weeks, which is how a nine-session plan
that plainly runs at four a week wherever it runs ends up rendered as
“1.67×/week”. peak is the honest answer.
average is still worth having, because it’s verifiable: it is exactly the
sum of byWeek’s sessions divided by byWeek’s length, so you can check it
against the array in the same response. The weeks it divides by span the
plan — the first session’s week through the last session’s, gap weeks
included — never your whole look-ahead window, so asking for a wide window
doesn’t dilute it.
The zero week is the most useful entry in byWeek. It’s a week inside the
plan where the supplier had nothing, not a hole in this data — and it’s what
lets you explain an uneven plan to a client (“week three is off, then you’re
back to four a week”) instead of apologising for one.
cadenceSummary behaves differently from its neighbours on a reschedule.
matchScore and matchComponents are provenance and are never re-derived,
but peak, average and byWeek are recomputed from the slate’s current
sessions every time the slate is rebuilt; only requested is snapshotted
from the original request. So a slate can come back from a reschedule with an
unchanged matchScore and a changed cadenceSummary.Why a slate departs from your request: matchNotes
matchScore says how well a slate matches. matchComponents says which
criterion missed. matchNotes says why — one entry per reason, each a
machine-readable code carrying the evidence behind it.
cadenceSummary above, explained: the
0 week is 2026-09-14, you asked for four sessions in it, and the plan placed
none. openingsInPool: 0 is the part that tells you why — the supplier’s
candidate pool held nothing placeable that week, so waiting is the move and
advice names the week to wait for.
There is deliberately no
message. No English ships in a note, so you keep
your own voice and can localise: write the copy, and use evidence to fill in
the week, the weekday or the count. A prewritten sentence would have to be
translated by every integrator anyway, and it would tempt you to render our
wording to a client instead of yours.matchNotes is always present. Nothing departed from your request means
[], not a missing key, so you can read .length without a null check. It is
not gated on matchScore either: a DIRECT_FILL slate and a PARTIAL
slate can both score 1 and still carry notes, and those are exactly the
slates worth captioning.
Weekday numbers anywhere in evidence are 0 = Sunday … 6 = Saturday —
the same numbering request-level daysOfWeek uses.
Group the week-level notes by code before you render them. One note is
emitted per short week, so a Monday-only supplier against a target of two emits
WEEK_SUPPLY_INSUFFICIENT on every week of the plan — a caption per note gives
you four near-identical sentences. Collapse each group into one line that names
the weeks: “four weeks come back short — 6, 13, 20 and 27 July”.
matchNotes and advice are provenance, like cadenceRrule: they record
what was true when the slate was generated. Rescheduling a session recomputes
startTimeConsistencyPercent, totalTravelTimeMins and cadenceSummary, but
not these — so a rescheduled slate can come back carrying a note its current
sessions no longer justify. Slates built before this shipped read back with
matchNotes: [] and no advice.The nine codes
WEEK_SUPPLY_INSUFFICIENT is the residual code, not a finding about supply.
Reaching it means only that the supplier’s working pattern is not empty — which
is what rules out SUPPLIER_UNAVAILABLE_WEEK, and is a fact about the weekdays
they work at all rather than a check of this calendar week — and that the
shortfall could not be attributed to one of your filters or to a cap. It does
not mean neither was involved. Two cases land here with one of them genuinely in
play:- a filter removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target);
- a cap applied to a week whose openings were already below your target
(
WEEK_CAPPEDis reserved for weeks that had enough openings to make the cap the thing to raise).
openingsInPool is below sessionsTargeted, the placeable days genuinely
weren’t there. When it’s at or above the target, the days were there and
something else was in the way — look for CADENCE_RELAXED on the same slate,
which reports a cadence that couldn’t use them and is the better thing to tell a
client. That pointer doesn’t always land: CADENCE_RELAXED is only emitted when
the cadence criterion scored below 1, and an authorised weekday
substitution scores a perfect cadence — so a days-were-there week can carry no
cadence note at all. When it doesn’t, say the week came back short and stop
there rather than naming a cause.openingsInPool counts placeable days, not slots: a plan places at most one
session per local date, so a day offering five start times counts once. That’s
what makes it directly comparable to sessionsTargeted.”Wait a week” or “loosen your days”
A week that comes back short of your target has two very different explanations, and they are opposite calls to action. One means the constraint is the supplier’s and yours can’t fix it; the other means the constraint is yours and one click fixes it. Tell a client the wrong one and you’ve either sent them away from a supplier who was available, or had them wait out a week that was never blocked. Getting this pair right is the reasonmatchNotes exists.
So the pair you actually branch on is WEEK_SUPPLY_INSUFFICIENT with an empty
pool against WEEK_EXCLUDED_BY_FILTERS.
The supplier had nothing open. No daysOfWeek filter, a target of two a
week, a Monday-to-Friday supplier whose diary is full across the week:
openingsInPool: 0 with no filter of yours named anywhere is as close as the
API gets to “there was nothing to book that week”. Waiting is the honest thing
to say, and advice is where you look next.
Your own filter cut the week down. daysOfWeek: [1] (Mondays only), the
same target of two a week, a Monday-to-Friday supplier with one open Monday in
the week:
supplierWorkdays: [1, 2, 3, 4, 5] against requestedDays: [1] is the whole
argument: one Monday a week can never make two sessions a week, and there are
four other weekdays this supplier works. Loosening daysOfWeek is the move
here, and waiting is not. supplierWorkdays is the pre-filter fact that makes
this call possible at all — the candidate pool alone can’t, because your
daysOfWeek and excludeDates were already applied to it, so “no openings this
week” looks identical whether the supplier had nothing or you removed
everything.
SESSIONS_EXHAUSTED means nothing went wrong
Nine sessions at four a week leaves the last week holding one. That week is
short of your target, and it is short for the most ordinary reason there is:
the package ran out of credits. Nothing failed.
sessionsPlacedBefore is how many of the package’s sessions the earlier weeks
already used — two of three here, so the final week could only ever hold one,
whatever the supplier’s diary looked like.
A hint about starting later: advice
With that stated, the shape is small:
advice is optional — present only when a later start would actually help.
It’s absent when you expressed no frequency target, when no week fell short, and
when no week in your window sustains the target from that point on. Absent is
the honest answer in all three cases; the field never points at a week that
doesn’t hold up.
“Sustain” is strict: every remaining whole week in your window, from
earliestSustainedWeek to the end of the window, holds at least your target in
open days — not just the named week itself. A week that meets the target and
then dips below it a fortnight later is never returned, because you’d hang a
client promise on it.
Read it alongside a WEEK_SUPPLY_INSUFFICIENT note carrying
openingsInPool: 0: that pairing says “waiting is the move”, and this field
names the week to wait for. In the 1 / 0 / 4 / 4 plan above, 2026-09-14 is the
empty week and earliestSustainedWeek is 2026-09-21 — the Monday supply
resumes and stays resumed. earliestSustainedWeek is always strictly later
than the first week the notes reported as short, so it never names a week the
same response has already called short.
Rescheduling a slot
POST /v1/projects/{projectId}/suggestions/slots/{slotId}/reschedule moves one
slot of a stored slate to a time the client picked, before anything is booked.
It’s the “can we do Thursday instead?” step. For the whole flow, from the
client’s pick to holding the adjusted slate, see
Let clients adjust a proposed slate. It doesn’t touch bookings: to
move a booking, see
Cancel or reschedule a booking.
- It must be in the future.
- The supplier must work then, with no booking or blocked time in the way.
- No live hold or booking may cover it on the supplier’s calendar.
200 returns the slot’s id and the whole slate, with its
totals worked out again:
slots[] is abridged.) Show the slate from this response rather than
patching the one slot on your side.
A reschedule reserves nothing. It moves the suggestion only. To keep the
new time for the client, hold the slate afterwards.
Reschedule before you hold or book, not after. The route doesn’t check
whether the slot was already held or booked, because a slot’s
reservationStatus is always FREE. Moving a held or booked slot changes
the slate only: the hold or booking keeps its old time. Two more things
follow from the calendar check:
- Your own hold counts as a conflict. Moving a slot into time you hold
yourself is
409 SLOT_HELD. - Two reschedules of one slot at once can both succeed. The last one wins.
When a reschedule is refused
Nearly every refusal is a409, and the causes need different handling.
Branch on code, not on the status.
SLOT_TIME_UNAVAILABLE names the supplier, the time and the length:
SLOT_NO_LONGER_FREE carries no suggestions:
freshSuggestions: a new plan worked out from the
original request, in the same shape as a POST /availability/package-slate
response. Show it instead of starting a new search. It’s null when no new
plan could be made, as for SLOT_NOT_FOUND, which has no request to plan
from:
freshSuggestions is abridged.)
A slate’s cadence fields record how it was first planned. A reschedule
doesn’t recheck them, so a moved slate can drift from its own cadenceRrule.
Endpoint index
POST /v1/projects/{projectId}/suggestions/slots/{slotId}/reschedulePOST /v1/projects/{projectId}/availability/package-slate— see Availability and slatesPOST /v1/projects/{projectId}/availability/package-options— see Show a package storefrontPOST /v1/projects/{projectId}/holds— see HoldsPOST /v1/projects/{projectId}/orders/{orderId}/package-bookings— see Create a package booking