> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Suggestions

> The plans the availability engine proposes for a package — suggestion requests, slates and slots, every field they carry, and the route that moves one slot before anything is booked.

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:

| Object | Id | What it is |
| - | - | - |
| Suggestion request | `sugreq_…` | One planning call, and everything it proposed. |
| Slate | `slate_…` | One complete plan: every session of the package, with one supplier. |
| Slot | `slot_…` | One session of a slate: a supplier, a time and a place. |

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](https://docs.gomarketbox.com/guides/availability-and-slates.md).

## 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](https://docs.gomarketbox.com/guides/availability-and-slates.md#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](https://docs.gomarketbox.com/guides/show-a-package-storefront.md).

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

| To | Call | With |
| - | - | - |
| Hold its sessions while the client pays | `POST /holds` | `slateId`, or `slotIds` for some of them. See [Holds](https://docs.gomarketbox.com/resources/holds.md). |
| Book its sessions now | `POST /orders/{orderId}/package-bookings` | `slateId` or `slotIds`. See [Create a package booking](https://docs.gomarketbox.com/guides/create-a-package-booking.md). |
| Book it as the signed-in client | `POST /clients/me/orders/{orderId}/package-bookings` | `slateId` or `slotIds` of a slate planned from that client's own order item. Any other is a `404`. See [Book a client's package credit](https://docs.gomarketbox.com/guides/book-a-package-credit.md). |
| Move one session to another time | `POST /suggestions/slots/{slotId}/reschedule` | The new start. See [Rescheduling a slot](#rescheduling-a-slot). |

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](https://docs.gomarketbox.com/guides/availability-and-slates.md#anatomy-of-a-slate) and
[Status values](https://docs.gomarketbox.com/guides/availability-and-slates.md#status-values).

### Response fields

| Field | Meaning |
| - | - |
| `status` | `OK`, `ALTERNATIVE_CADENCE`, `NO_COMPLETE_SLATE`, or `NO_AVAILABILITY` — see [Status values](https://docs.gomarketbox.com/guides/availability-and-slates.md#status-values). |
| `reason` | Human-readable explanation when `status` isn't `OK`. `null` on success. |
| `suggestionRequestId` | Audit id for this request. Present only when `persist` is `true` (the default). |
| `resolvableUntil` | Slates and slots stay resolvable (holdable/bookable by id) for **24 hours** from the request; after that they're stale. |
| `primarySlate` | The best **COMPLETE** single-supplier slate — book this by `slateId`. `null` if none satisfies the project's supplier policy. |
| `alternates` | Other bookable options beyond `primarySlate`, ranked best first and capped at the request's `maxAlternates` (default `3`; `0` returns none). Under the default `supplierPolicy` of `SAME_SUPPLIER` these are other schedules from the same supplier as `primarySlate`; under `PREFERRED` or `ANY` they're other suppliers' best schedules, one per supplier. Each entry's `slateId` is bookable exactly like `primarySlate`'s. |
| `partial` | The best **PARTIAL** slate (fills fewer than the requested sessions). `null` unless the project has `suggestionConfig.allowPartialPackages` enabled. |
| `cadenceAlternatives` | **COMPLETE** N-session slates at a *different, supplier-feasible* cadence than the one you asked for. Sorted closest-first by `cadenceDistance` — unless you sent `sessionsPerWeek`, in which case closeness to that frequency target is the primary sort key, ahead of `cadenceDistance`. Always `[]` unless the request opted in — see [Cadence relaxation](https://docs.gomarketbox.com/guides/availability-and-slates.md#cadence-relaxation). |
| `requestedCadence` | The `rrule` this request asked for, echoed back so you can diff it against each slate's `cadenceRrule`. `null` when the request named no cadence. |

> [!NOTE]
>
> 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:

| Field | Meaning |
| - | - |
| `slateId` | Hold or book the whole plan with this — pass it as `slateId` to `POST /holds` or `POST .../package-bookings`. |
| `supplierId` | The single supplier this slate is built from. |
| `completeness` | `COMPLETE` when every session is filled, `PARTIAL` when not. |
| `sessionsRequested` / `sessionsFilled` | How many of the package's sessions this plan could fill, out of how many were requested. |
| `startTimeConsistencyPercent` | How consistent the session start times are (0–100). |
| `matchScore` | How well this slate matches the requested schedule preferences, `0`–`1` — the mean of the components in `matchComponents`. `1` with an empty `matchComponents` means no schedule preference was expressed, not a perfect match. See [How well a slate matches: `matchScore` and `matchComponents`](#how-well-a-slate-matches-matchscore-and-matchcomponents) below. |
| `matchComponents` | The per-criterion breakdown behind `matchScore` — carries only the criteria you actually supplied and that were scoreable for this slate. Present on every fresh availability response, empty when nothing was asked; absent entirely only on a slate resolved from a pre-existing booking rather than a fresh call — see below. |
| `cadenceSummary` | How often this plan actually runs, week by week, against the frequency you asked for: `requested`, `peak`, `average`, and a `byWeek` array. **Render `peak`, not `average`.** Present on every slate holding at least one session, on **every** request path — including the default `cadenceFlexibility: "NONE"` — and absent only for a slate with no sessions. See [How often a plan runs: `cadenceSummary`](#how-often-a-plan-runs-cadencesummary) below. |
| `matchNotes` | **Why** this slate departs from what you asked for — an array of coded reasons, each with structured evidence and no English. **Always present**; `[]` means nothing departed. Not gated on `matchScore`. See [Why a slate departs from your request: `matchNotes`](#why-a-slate-departs-from-your-request-matchnotes) below. |
| `advice` | An optional, **advisory** hint that starting later would help: `code` plus `earliestSustainedWeek`. It reports that supply exists from that week onward — not that a slate was built or would be bookable. Present only when one applies. See [A hint about starting later: `advice`](#a-hint-about-starting-later-advice) below. |
| `totalTravelTimeMins` | Summed travel time across the plan's sessions. |
| `slots[]` | The resolved sessions — see below. |

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](https://docs.gomarketbox.com/guides/availability-and-slates.md#cadence-relaxation):

| Field | Meaning |
| - | - |
| `cadenceRrule` | The recurrence rule this slate's sessions actually follow. **`null` for a direct fill** — that plan follows no recurrence rule at all. |
| `matchesRequestedCadence` | `true` when `cadenceRrule` is the `rrule` you asked for. |
| `cadenceRelaxation` | How the cadence was derived: `EXACT`, `INTERVAL_TIGHTENED` (same weekdays, run more often), `DAYS_ADDED` (every requested weekday kept, more added), `DAYS_SUBSTITUTED` (requested weekdays replaced with ones the supplier works), `ALL_WORKING_DAYS`, or `DIRECT_FILL`. |
| `cadenceDistance` | How far this cadence sits from the requested one — `0` is exact, lower is closer. `cadenceAlternatives` is sorted by it — unless the request sent `sessionsPerWeek`, in which case closeness to that frequency target sorts first, and `cadenceDistance` only breaks ties within it. |

> [!NOTE]
>
> 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`](#how-often-a-plan-runs-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[]`:

| Field | Meaning |
| - | - |
| `slotId` | Id of one session. Hold, book or reschedule one session with it. Pass a subset of these as `slotIds` to cherry-pick instead of booking the whole slate. |
| `sessionIndex` | **1-based** position within the slate. |
| `supplierId`, `serviceId`, `offeringId` | Resolved identifiers for this session. |
| `bookingStartUtc`, `bookingEndUtc`, `bookingTz` | The resolved time. `bookingTz` is the session's **home zone** — the service location's zone, else the supplier's, else the project default — not the `timezone` you sent on the request. |
| `locationType`, `locationId`, `latitude`, `longitude`, `address` | The resolved location — for `TRAVEL_ZONE` slates the engine fills `locationId` (the supplier's travel-zone id) and stamps the request's `address` onto every slot. Holding or booking a slot copies these, so you send no location. |
| `travelTimeMins` | Travel time to this session. |
| `capacity` | Session capacity. |
| `reservationStatus` | **Deprecated and inert** — always `FREE`. Holds are claims on *supplier time*, not on slot rows, so this field no longer tracks anything. Don't branch on it; see [Hold slots during checkout](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md). |

> [!TIP]
>
> **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](https://docs.gomarketbox.com/guides/create-a-package-booking.md).

### 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:

| Component | Scored when | Meaning |
| - | - | - |
| `startDate` | you sent `lookAheadStartDate` | how soon session one lands — `1` when it lands on the window's first day, lower the later it lands |
| `timeOfDay` | you sent `preferredTimes` | fraction of this slate's sessions that fall at a preferred time |
| `daysOfWeek` | you sent `daysOfWeek` | fraction of this slate's sessions that fall on a requested weekday |
| `sessionsPerWeek` | you sent `sessionsPerWeek` | fraction of the window's whole weeks in which this slate holds **at least** the target number of sessions — a ratio in `0`–`1`, never a count. For counts, read [`cadenceSummary`](#how-often-a-plan-runs-cadencesummary), which buckets weeks differently |
| `cadence` | you sent `rrule` **and** the slate follows a cadence | see below |

`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".

> [!WARNING]
>
> 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.

```json theme={null}
{
  "cadenceSummary": {
    "requested": 4,
    "peak": 4,
    "average": 2.25,
    "byWeek": [
      { "weekStart": "2026-09-07", "sessions": 1 },
      { "weekStart": "2026-09-14", "sessions": 0 },
      { "weekStart": "2026-09-21", "sessions": 4 },
      { "weekStart": "2026-09-28", "sessions": 4 }
    ]
  }
}
```

| Field | Meaning |
| - | - |
| `requested` | The frequency you asked for, in sessions per week — your `sessionsPerWeek` target when you sent one, otherwise the number of weekdays your own `rrule` named (`FREQ=WEEKLY;BYDAY=MO,TU,WE,TH` is `4`). `null` when you expressed no frequency at all, and `null` too when the rule wasn't yours to count: a non-weekly `FREQ`, an `INTERVAL` other than `1`, a weekly rule naming no weekdays, or a cadence this API synthesised on your behalf. Reporting a frequency you never asked for is worse than reporting none. |
| `peak` | The most sessions this plan holds in any single week. **This is the number to render.** |
| `average` | Sessions divided by the number of entries in `byWeek`, to two decimal places. For capacity and reporting — not for client-facing copy. |
| `byWeek` | Every **Monday-anchored** week from the first session's week through the last session's: ascending, contiguous, and including weeks holding `0` sessions. Never empty. |

**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.

> [!WARNING]
>
> **`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`](https://docs.gomarketbox.com/guides/search-suppliers-by-availability).
>
> 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.

> [!NOTE]
>
> `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.

```json theme={null}
{
  "matchNotes": [
    {
      "code": "WEEK_SUPPLY_INSUFFICIENT",
      "component": "sessionsPerWeek",
      "weekStart": "2026-09-14",
      "evidence": {
        "sessionsPlaced": 0,
        "sessionsTargeted": 4,
        "openingsInPool": 0
      }
    }
  ]
}
```

That single note is the 1 / 0 / 4 / 4 plan from
[`cadenceSummary`](#how-often-a-plan-runs-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.

| Field | Meaning |
| - | - |
| `code` | Which reason this is — one of the nine below. The discriminator: each code carries its own `evidence` shape, so your generated types tell you exactly which fields are present rather than handing you a bag of optionals. |
| `component` | The `matchComponents` criterion this note explains — `sessionsPerWeek`, `cadence`, `timeOfDay` or `startDate`. Group notes by it to caption a component directly. Present on eight of the nine codes; `PACKAGE_UNDERFILLED` has **no** `component`, because plan size isn't a scored criterion. A pointer, not a join key: the week-level codes bucket Monday-anchored calendar weeks while `matchComponents.sessionsPerWeek` buckets 7-day blocks from your window's start, so a note can name a short week for a criterion that component scores as met, and the reverse. |
| `weekStart` | The Monday (`YYYY-MM-DD`, local) of the week this note is about. Only on the five week-level codes, and bucketed exactly like `cadenceSummary.byWeek`, so a note joins to a `byWeek` entry on this key. |
| `evidence` | The numbers behind the code — counts, weekdays, dates. Its shape is fixed per code. |

> [!NOTE]
>
> **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".

> [!NOTE]
>
> `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

| Code | `component` | Emitted when | What it licenses you to say |
| - | - | - | - |
| `SUPPLIER_UNAVAILABLE_WEEK` | `sessionsPerWeek` | The supplier works **none** of the weekdays that could have served this week — `evidence.supplierWorkdays` is `[]`. **Not currently emitted by the live engine** — see the section below before you build for it. | "This supplier doesn't work any of the days that week needed — the sessions moved to the weeks either side." Check `advice` for the earliest week supply resumes. |
| `WEEK_EXCLUDED_BY_FILTERS` | `sessionsPerWeek` | Your own `daysOfWeek` or `excludeDates` cut this week's candidate days below your target, and the supplier's working **pattern** covers enough days in the week to have met it without your filter. `evidence.filter` names which one. Like `supplierWorkdays` everywhere else, that is a pattern fact, not a check of this calendar week — a supplier already booked solid across it reports this code too. | "Your day preferences are what's limiting this week — allowing one more weekday is the thing most likely to fill it." Say *likely*: loosening the filter is the best move the evidence supports, not a guarantee. |
| `WEEK_SUPPLY_INSUFFICIENT` | `sessionsPerWeek` | The week is short and none of the more specific reasons could be **established**. This is the residual code: the supplier's working *pattern* is not empty (which is what rules out `SUPPLIER_UNAVAILABLE_WEEK` — a pattern fact, not a check of this calendar week), and the shortfall could not be attributed to one of your filters or to a cap you sent — which is not the same as those playing no part. | Don't lead with "the supplier didn't have enough open days" — compare `sessionsPlaced` and `sessionsTargeted` against `openingsInPool` first, and see the note below for the two cases where a filter or a cap *was* involved. |
| `WEEK_CAPPED` | `sessionsPerWeek` | The week held at least `sessionsTargeted` placeable days, and a cap **you** sent puts a ceiling on the week below your target — so the target was unreachable there whatever the supplier had free. `evidence.cap` is `maxSessionsPerWeek` or `minGapDays`, with its `capValue`. It fires on the ceiling *existing*, not on the plan having filled up to it. | "That week is capped by your own settings — raise the cap for a denser week." Raising it is **necessary**; whether it's **sufficient** this note can't say. If `sessionsPlaced` sits below the ceiling the cap implies, all you know is that the plan didn't fill the week even to the ceiling — don't read a second cause into it. |
| `SESSIONS_EXHAUSTED` | `sessionsPerWeek` | The week is short only because the package ran out of sessions. | Nothing apologetic — see the dedicated section below. |
| `CADENCE_RELAXED` | `cadence` | The slate doesn't run at the `rrule` you sent. `evidence.cadenceRelaxation` says how the cadence was derived; `requestedDays` and `actualDays` let you show the swap. | "We moved your Tuesdays to Thursdays" / "this plan runs weekly rather than fortnightly." |
| `SESSIONS_OUTSIDE_PREFERRED_TIMES` | `timeOfDay` | Some sessions fall outside every `preferredTimes` window you sent. `evidence.sessionIndexes` is **1-based** and matches `sessionIndex` on the slots; `localTimes` is aligned to it. **Both arrays can be empty** — when no session lands inside your requested window at all, the criterion definitely missed but there is no in-window session to name. | "Sessions 3 and 7 are at 08:00, outside your afternoon preference." Handle the empty case: caption it "outside your preferred times" with no session list, not as an error. |
| `FIRST_SESSION_LATE` | `startDate` | The plan's first session is `evidence.dayOffset` whole days after your window start — always at least one. That offset is the fact; whether the plan started later than it *had* to is a separate question. | Branch on `evidence.earlierSupplyExisted`. `true`: the supplier *was* free earlier and the cadence couldn't use those days, so "we could have started on the 7th — loosening the cadence is the fix." `false`: no earlier opening existed in your window, so "the earliest this supplier opens is the 14th" — nothing was given up, and copy implying otherwise is wrong. |
| `PACKAGE_UNDERFILLED` | *(none)* | Fewer sessions than the package holds credits for. | "We could only plan 6 of the 8 sessions." `completeness` says `PARTIAL` too. |

> [!NOTE]
>
> **`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.

> [!WARNING]
>
> **`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:

```json theme={null}
{
  "code": "WEEK_SUPPLY_INSUFFICIENT",
  "component": "sessionsPerWeek",
  "weekStart": "2026-07-06",
  "evidence": {
    "sessionsPlaced": 0,
    "sessionsTargeted": 2,
    "openingsInPool": 0
  }
}
```

`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:

```json theme={null}
{
  "code": "WEEK_EXCLUDED_BY_FILTERS",
  "component": "sessionsPerWeek",
  "weekStart": "2026-07-06",
  "evidence": {
    "sessionsPlaced": 1,
    "sessionsTargeted": 2,
    "filter": "daysOfWeek",
    "supplierWorkdays": [1, 2, 3, 4, 5],
    "requestedDays": [1]
  }
}
```

`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.

> [!WARNING]
>
> **`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.

```json theme={null}
{
  "code": "SESSIONS_EXHAUSTED",
  "component": "sessionsPerWeek",
  "weekStart": "2026-07-20",
  "evidence": {
    "sessionsRequested": 3,
    "sessionsPlacedBefore": 2
  }
}
```

`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.

> [!WARNING]
>
> **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`

> [!WARNING]
>
> **`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:

```json theme={null}
{
  "advice": {
    "code": "LATER_START_IMPROVES_CADENCE",
    "earliestSustainedWeek": "2026-09-21"
  }
}
```

| Field | Meaning |
| - | - |
| `code` | Always `LATER_START_IMPROVES_CADENCE` today. Branch on it anyway — it's an enum so more hints can be added without a breaking change. |
| `earliestSustainedWeek` | The earliest Monday (`YYYY-MM-DD`, local) from which supply alone could sustain your requested frequency. |

`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](https://docs.gomarketbox.com/guides/adjust-a-proposed-slate.md). It doesn't touch bookings: to
move a booking, see
[Cancel or reschedule a booking](https://docs.gomarketbox.com/guides/cancel-or-reschedule-a-booking.md).

```json theme={null}
{ "bookingStartUtc": "2026-07-16T20:00:00.000Z" }
```

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:

```json theme={null}
{
  "slotId": "slot_01kx16ejsqffc9rbgdcc591w2q",
  "slate": { "slateId": "slate_01kx16ejsqffc9rbgdcc591w2p", "slots": [] }
}
```

(`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.

| Status | `code` | Meaning | What to do |
| - | - | - | - |
| `400` | `BAD_REQUEST` | `bookingStartUtc must be in the future`. | Send a future time. |
| `400` | `VALIDATION_ERROR` | `bookingStartUtc` isn't an ISO-8601 instant. | Fix the value. |
| `409` | `SLOT_TIME_UNAVAILABLE` | The supplier doesn't work then, or a booking or blocked time is in the way. | Offer another time. The slate is unchanged. |
| `409` | `SLOT_HELD`, `SLOT_BOOKED` | A hold or a booking already covers the new time. The body names it in `conflicts[]`, as on [Placing a hold](https://docs.gomarketbox.com/resources/holds.md#placing-a-hold). | Offer another time. |
| `409` | `SLOT_NO_LONGER_FREE` | The slot or its slate was removed, or a concurrent write cancelled the move. | Retry once. |
| `409` | `SLOT_NOT_FOUND` | No slot has that id. | Plan a new slate. |
| `409` | `SUGGESTION_EXPIRED` | The slot is past its 24-hour window. | Show `freshSuggestions`. |
| `409` | `SLOT_NOT_BOOKABLE`, `SLATE_NOT_FOUND` | The slot or its slate can no longer be used. | Show `freshSuggestions`. |

`SLOT_TIME_UNAVAILABLE` names the supplier, the time and the length:

```json theme={null}
{
  "code": "SLOT_TIME_UNAVAILABLE",
  "message": "Supplier sup_01kv60qgnef2kt3pvqgwmkbzfr is not available at 2026-07-16T20:00:00.000Z for 60 minutes",
  "statusCode": 409,
  "requestId": "5c2e8a1f-7d4b-4e69-b0a3-1f9d6c2e8b47"
}
```

`SLOT_NO_LONGER_FREE` carries no suggestions:

```json theme={null}
{
  "code": "SLOT_NO_LONGER_FREE",
  "message": "Slot slot_01kx16ejsqffc9rbgdcc591w2q could not be rescheduled (no longer FREE or not found)",
  "statusCode": 409,
  "requestId": "2f7a4c9e-1b6d-4a83-b5e0-8d3c1f7a2e96"
}
```

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:

```json theme={null}
{
  "code": "SUGGESTION_EXPIRED",
  "message": "Slot slot_01kx16ejsqffc9rbgdcc591w2q is past its resolvable window",
  "statusCode": 409,
  "requestId": "8b1d5f3a-6c2e-4d97-a0b4-3e7f9c1a5d28",
  "freshSuggestions": {
    "status": "OK",
    "suggestionRequestId": "sugreq_01kx19m3x7ab4c2d9e5f6g7h8j",
    "primarySlate": { "slateId": "slate_01kx19m3x7ab4c2d9e5f6g7h8k", "slots": [] }
  }
}
```

(`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](https://docs.gomarketbox.com/guides/availability-and-slates.md)
* `POST /v1/projects/{projectId}/availability/package-options` — see [Show a package storefront](https://docs.gomarketbox.com/guides/show-a-package-storefront.md)
* `POST /v1/projects/{projectId}/holds` — see [Holds](https://docs.gomarketbox.com/resources/holds.md)
* `POST /v1/projects/{projectId}/orders/{orderId}/package-bookings` — see [Create a package booking](https://docs.gomarketbox.com/guides/create-a-package-booking.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.