Skip to main content
A suggestion is the availability engine’s proposal for when a package’s sessions could happen. It’s a hint, not a booking: nothing is reserved until you hold or book it. A suggestion has three levels: 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-slate plans one package, or the sessions left on an order item. See Anatomy of a slate.
  • POST /v1/projects/{projectId}/availability/package-options plans every ACTIVE package of a service in one call. See Show a package storefront.
A planning call stores what it proposed unless you send 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’s resolvableUntil 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.
Each entry in slots[]:
Off-by-one trap. sessionIndex is 1-based here in the slate’s slots[], but 0-based in the created[] array returned by POST .../package-bookings (and .../convert). Don’t compare them directly without adjusting — see Create a package booking.

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:
  • 1 when the slate runs at the rrule you requested.
  • 1 also when the only departure was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution: true (the default) and no daysOfWeek sent. Naming your weekdays withdraws that authorisation, because it says the weekdays are the point.
  • 0 when 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: a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so the question is unanswerable rather than answered zero. Absent too when you sent no rrule.
A request that expresses no schedule preference at all gets 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”.
Results already arrive ranked. primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order; completeness always outranks matchScore, so a COMPLETE slate is never placed below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.)Don’t re-sort the slates you receive by matchScore. The order carries a preference the number can’t. matchComponents.sessionsPerWeek scores a week holding at least the target, so against a target of 2 a slate delivering three sessions a week scores exactly the same as one delivering two — only the order distinguishes them. Re-sorting silently discards “two, not three”.

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 and matchComponents.sessionsPerWeek count weeks differently, on purpose. They are not two views of the same number:
  • cadenceSummary.byWeek buckets Monday-anchored calendar weeks, so every weekStart is a real Monday and the buckets agree with how the maxSessionsPerWeek cap counts.
  • matchComponents.sessionsPerWeek — the 0–1 ratio above, not a count — buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on POST /availability/suppliers.
They can therefore disagree, and both are right. peak: 4 against a target of 4 while that component reads below 1 is exactly what a supplier’s mid-plan break looks like: every week the plan runs, it runs at four — but the whole weeks of your window don’t all hold four. Don’t file that as a bug.
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.
That single note is the 1 / 0 / 4 / 4 plan from 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_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise).
So read the evidence rather than assuming supply was the constraint. When 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 reason matchNotes exists.
SUPPLIER_UNAVAILABLE_WEEK is not currently emitted by the live engine. It is part of the published contract and you should keep it in your switch — but it fires only when a supplier works no weekday at all, and a supplier like that produces no availability, so no candidate, so no slate for the note to attach to. Don’t build your “waiting helps” copy on it: nothing will reach it today.The supplier-break case reaches you as WEEK_SUPPLY_INSUFFICIENT with openingsInPool: 0. That is the combination to key your “waiting may help” copy on, and advice.earliestSustainedWeek is the week to name.
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.
supplierWorkdays is a fact about the supplier’s working pattern, not a check of that particular calendar week — and this is true wherever it appears, on WEEK_EXCLUDED_BY_FILTERS as much as on SUPPLIER_UNAVAILABLE_WEEK. The API answers “which weekdays does this supplier work at all”, never “was this specific week covered” — answering the second would mean re-expanding every recurrence rule on the booking hot path.Two consequences worth designing for. A supplier who works Mondays but happens to be booked out on this week’s Monday reports WEEK_SUPPLY_INSUFFICIENT, not SUPPLIER_UNAVAILABLE_WEEK. And a Monday-to-Friday supplier who is booked solid across the week still reports WEEK_EXCLUDED_BY_FILTERS if your daysOfWeek narrowed it — the pattern days were there even though the openings weren’t. So treat “loosen your filter” as the most likely fix rather than a guaranteed one; it is the best move the evidence supports, but the API has not checked that those extra weekdays were free.WEEK_EXCLUDED_BY_FILTERS is still only emitted when relaxing your filter could have helped: a week the supplier’s own pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead, and is not your filter’s fault. The one exception is a daysOfWeek naming no day this supplier works at all, which leaves zero candidate days whatever your target.

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.
Don’t apologise for SESSIONS_EXHAUSTED, and don’t surface it as a problem. It outranks every supply code: when it’s emitted for a week, no SUPPLIER_UNAVAILABLE_WEEK, WEEK_EXCLUDED_BY_FILTERS, WEEK_SUPPLY_INSUFFICIENT or WEEK_CAPPED is emitted for that same week. It exists precisely so a correctly-filled plan doesn’t read as a supplier failure — without it, the tail week of every package looks like something went wrong. Render it as a plain fact if you render it at all (“the last week runs once — that’s the eighth and final session”), or drop it.

A hint about starting later: advice

advice is advisory only. It reports that the supplier has enough open supply from a given week onward to sustain the frequency you asked for. It does not mean a slate was built for that week, or that one would be bookable — holds, capacity, travel time and the cadence rules all still apply. Re-request with a later lookAheadStartDate to find out for real. Don’t promise a client a schedule nobody has validated.
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.
Only the start moves. The slot keeps its length, time zone, place and supplier. The new time is checked, not trusted:
  • 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.
Travel time between this session and the ones around it isn’t checked, and neither is a clash with the slate’s other sessions. On success, the 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.
The checks run in order: the slot exists, it’s within its 24-hour window, then the new time is in the future, then the supplier is free.

When a reschedule is refused

Nearly every refusal is a 409, 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:
The stale codes come with 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}/reschedule
  • POST /v1/projects/{projectId}/availability/package-slate — see Availability and slates
  • POST /v1/projects/{projectId}/availability/package-options — see Show a package storefront
  • POST /v1/projects/{projectId}/holds — see Holds
  • POST /v1/projects/{projectId}/orders/{orderId}/package-bookings — see Create a package booking