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

# Availability and slates

> A deep dive into the clusters/availability engine — slate anatomy, cadence rules, and the advanced booking paths that sit alongside book-by-slateId.

This is the deep-dive companion to
[Create a package booking with a slate](https://docs.gomarketbox.com/guides/create-a-package-booking.md). That
guide covers the primary flow — build a slate, create an order, book it by
`slateId` — end to end. This page goes underneath it: what the five
availability endpoints are for, how to read a slate response, the cadence
rules that shape it, what happens when a supplier can't meet those rules, and
the two advanced booking paths that exist alongside book-by-`slateId`.

Every field of a slate response, slate and slot is documented in
[Suggestions](https://docs.gomarketbox.com/resources/suggestions.md#anatomy-of-a-slate-and-a-slot).

It builds on [The booking engine model](https://docs.gomarketbox.com/concepts/booking-engine-model.md) —
read the [Slates](https://docs.gomarketbox.com/concepts/booking-engine-model.md#slates) section first if you
haven't.

## The availability engine

Five endpoints make up the availability engine, all authenticated with the
`x-api-key` header (see the table below for exact paths). They're layers of
the same clustering engine, from lowest to highest level:

| Endpoint | Use it when |
| - | - |
| `POST .../availability/time-slots` | You already hold the scheduling state (suppliers, their bookings, their availability) and want to run the engine directly, passing everything in the body. |
| `POST .../availability/search` | You have a service + offering + location and want the API to resolve suppliers from project data and return suggested/open slots — one-off, single-session slots. |
| `POST .../availability/suppliers` | You want the same single-session availability **grouped by supplier** — a paginated list of supplier profiles, each with its open slots bucketed by local day. Reach for it when rendering a wall of supplier cards. |
| `POST .../availability/package-slate` | You want a **complete N-session plan** for a package from one supplier, computed from a recurrence rule (`rrule`). This is the endpoint the rest of this guide covers. |
| `POST .../availability/package-options` | You want **every** ACTIVE package of a service planned in one call, each with its own ready-to-book `slateId`. The composite built on `package-slate` — reach for it when rendering a package storefront. |

> [!NOTE]
>
> `/search`, `/time-slots` and `/suppliers` are documented in full in the
> [Availability resource reference](https://docs.gomarketbox.com/resources/availability.md) — 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](https://docs.gomarketbox.com/resources/availability.md#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](https://docs.gomarketbox.com/guides/create-a-package-booking.md#book-the-sessions-left-on-a-credit). The response is a
`PackageSlateResponse`:

```json theme={null}
{
  "status": "OK",
  "reason": null,
  "suggestionRequestId": "sugreq_01kx16ej7pe4r9da74adf6m4h0",
  "resolvableUntil": "2026-07-10T00:00:00.000Z",
  "primarySlate": {
    "slateId": "slate_01kx16ejsqffc9rbgdcc591w2p",
    "supplierId": "sup_01kv60qgnef2kt3pvqgwmkbzfr",
    "completeness": "COMPLETE",
    "sessionsRequested": 8,
    "sessionsFilled": 8,
    "startTimeConsistencyPercent": 100,
    "matchScore": 1,
    "matchComponents": { "startDate": 1, "cadence": 1 },
    "totalTravelTimeMins": 0,
    "slots": []
  },
  "alternates": [],
  "partial": null,
  "cadenceAlternatives": [],
  "requestedCadence": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;COUNT=8"
}
```

(`slots[]` abridged to `[]` here — see [Create a package booking](https://docs.gomarketbox.com/guides/create-a-package-booking.md)
for a fully populated example, and [Slate and slot fields](https://docs.gomarketbox.com/resources/suggestions.md#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

| `status` | Meaning |
| - | - |
| `OK` | A `COMPLETE` primary slate was found — every requested session filled by one supplier. |
| `ALTERNATIVE_CADENCE` | **A success, returned as `200`.** No slate at the *requested* cadence, but `cadenceAlternatives` holds one or more complete plans at a denser, supplier-feasible cadence. `primarySlate` is `null`; every alternative's `slateId` is bookable exactly like `primarySlate`'s. Only ever returned when the request opted in via `cadenceFlexibility` or `guaranteeSlate`. |
| `NO_COMPLETE_SLATE` | No complete single-supplier slate exists under the project's supplier policy. `alternates` may still be populated **under any `supplierPolicy`, including the default `SAME_SUPPLIER`** — here they're the same supplier's other PARTIAL schedules, so booking one still depends on `allowPartialPackages`. `partial` may also be usable (if `allowPartialPackages` is on) — check both before treating this as a dead end. |
| `NO_AVAILABILITY` | No availability at all for the request window — no supplier, complete or partial. |

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

### Read the rest of the response

The field-by-field reference for a slate is in
[Suggestions](https://docs.gomarketbox.com/resources/suggestions.md#anatomy-of-a-slate-and-a-slot):

* [Response fields](https://docs.gomarketbox.com/resources/suggestions.md#response-fields): `primarySlate`,
  `alternates`, `partial`, `cadenceAlternatives` and the rest of the envelope.
* [Slate and slot fields](https://docs.gomarketbox.com/resources/suggestions.md#slate-and-slot-fields):
  every field of a slate, its cadence provenance, and each entry in `slots[]`.
* [How well a slate matches: `matchScore` and `matchComponents`](https://docs.gomarketbox.com/resources/suggestions#how-well-a-slate-matches-matchscore-and-matchcomponents).
  Don't re-sort the slates you receive by `matchScore`.
* [How often a plan runs: `cadenceSummary`](https://docs.gomarketbox.com/resources/suggestions#how-often-a-plan-runs-cadencesummary).
  Render `peak`, not `average`.
* [Why a slate departs from your request: `matchNotes`](https://docs.gomarketbox.com/resources/suggestions#why-a-slate-departs-from-your-request-matchnotes),
  with [the nine codes](https://docs.gomarketbox.com/resources/suggestions.md#the-nine-codes) and
  [a hint about starting later: `advice`](https://docs.gomarketbox.com/resources/suggestions#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`

```
✅ FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;COUNT=8
❌ FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR
```

An unbounded `rrule` almost never returns anything bookable — the engine
needs a specific number of occurrences to try to fill, not an open-ended
pattern. Omitting `COUNT` (or giving `COUNT=0`) fails validation:

```json theme={null}
{
  "code": "VALIDATION_ERROR",
  "message": "rrule: 'rrule' must include a bounded COUNT (e.g. 'FREQ=WEEKLY;BYDAY=MO;COUNT=8')",
  "statusCode": 400,
  "requestId": "4b8e2f1a-7c9d-4a56-b3e0-8d5f1c9a4e67"
}
```

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

```
✅ 2026-07-09T00:00:00-04:00
❌ 2026-07-09T00:00:00Z
```

The slate builder derives the request's UTC offset from the **last six
characters** of `lookAheadStartDate`, so a `Z` suffix would produce a garbage
offset and silently wrong results — the API rejects it outright instead:

```json theme={null}
{
  "code": "VALIDATION_ERROR",
  "message": "lookAheadStartDate: 'lookAheadStartDate' must carry a numeric timezone offset (e.g. '2026-07-01T00:00:00-04:00'), not a 'Z' suffix",
  "statusCode": 400,
  "requestId": "a6d3f9e8-2b5c-4d17-9e04-6a8c3f1b5d92"
}
```

Make the offset the zone's real offset for that date — Toronto is `-04:00`
in summer but `-05:00` in winter. The `timezone` alongside it must be an
IANA identifier (`America/Toronto`, never `EST`); see
[Timezones](https://docs.gomarketbox.com/concepts/timezones.md#valid-timezones).

> [!NOTE]
>
> This guard is specific to the two package endpoints. Recurring
> `POST …/availability/search` accepts a `Z` instant since September 10, 2026.

### The 120-day look-ahead ceiling

You don't have to compute the look-ahead window yourself — by default it's
**derived from your cadence and the package's `creditCount`**, so the engine
searches exactly as far ahead as it needs to fit every session. That
derived window is capped at **120 days**.

That ceiling is wide enough for the ordinary weekly product. A weekly
10-session package (`FREQ=WEEKLY;BYDAY=MO;COUNT=10`) spans about 70 days —
comfortably inside the window — so it plans and books normally. Weekly
12-packs (\~84 days) and biweekly 5-packs (\~70 days) fit too.

What happens when the cadence is too sparse to fit all of a package's
sessions within 120 days **depends on whether you asked for cadence
flexibility**. The two behaviours are genuinely different code paths:

| `cadenceFlexibility` | Behaviour when the derived window exceeds 120 days |
| - | - |
| `NONE` (the default) | **Fails fast with a `422` before running the engine at all**, naming the exact window it would have needed. Nothing is silently truncated. |
| `FALLBACK` / `ALWAYS` (or `guaranteeSlate: true`) | **Clamps the window to 120 days and runs the engine anyway.** No early return. |

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](#cadence-relaxation)
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](https://docs.gomarketbox.com/concepts/errors.md) (the `reason` becomes
`message` and the `status` becomes `code`), **not** a `200` with a slate body:

```json theme={null}
{
  "code": "NO_COMPLETE_SLATE",
  "message": "package cadence requires 134-day availability window for 20 sessions, which exceeds the 120-day maximum",
  "statusCode": 422,
  "requestId": "1f5b8d3a-4e9c-4a72-b6d1-3f0a8c5e2b46"
}
```

Send the *same* request with `cadenceFlexibility: "FALLBACK"` and you get a
`200` instead: the window clamps to 120 days, the engine runs, and any
complete denser plan the supplier can actually fill comes back in
`cadenceAlternatives` with `status: "ALTERNATIVE_CADENCE"`. If even the
relaxed cadences fail, it's a `422` again — the clamp buys the engine a
chance to answer, it doesn't manufacture availability.

Compare that to the working example from
[Create a package booking](https://docs.gomarketbox.com/guides/create-a-package-booking.md): 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.

> [!TIP]
>
> If you need a window wider than the derived default, pass `lookAheadDays` or
> `endDate` explicitly. **Doing so skips the derivation entirely — you own the
> window.** Neither the 120-day cap nor the relaxation padding is applied to a
> window you sized yourself: the 120 is a ceiling on the window the API
> *derives* from your cadence, not a ceiling the engine enforces on a window you
> state outright. So an explicit `lookAheadDays: 200` really does search 200
> days.
>
> The trade is that nothing sanity-checks it for you. Too small and the cadence
> can't fit; too large and you pay for pool the engine has to build. See the
> warning below for what an explicit window costs a relaxation request
> specifically.

> [!WARNING]
>
> **An explicit `lookAheadDays` or `endDate` also opts you out of the padding
> that cadence relaxation relies on.** When the window is derived, a relaxation
> request widens it by a few days so a weekday *substitution* — which can need a
> slightly longer span than the cadence you asked for — has room to land. Size
> the window yourself and that padding is gone, so a substituted cadence needing
> a handful more days is silently dropped from `cadenceAlternatives`. If you're
> combining `cadenceFlexibility` with an explicit window, budget a week of
> headroom, or let the derivation do it for you.

## Cadence relaxation

A supplier who works every weekday still can't give you eight *Fridays* if
their schedule only runs four weeks. Historically that returned an empty
`422` and left you with nothing to show — the single biggest complaint
against the booking engine.

Now you can ask the engine to answer with a **denser, supplier-feasible
cadence** instead: complete N-session plans that fit the supplier's real
availability but don't follow the `rrule` you asked for. They arrive in
`cadenceAlternatives`, each with a directly bookable `slateId`.

> [!WARNING]
>
> **This is strictly opt-in, and the opt-in is absolute.** A request that sets
> neither `cadenceFlexibility` nor `guaranteeSlate` behaves *exactly* as it did
> before this feature existed — same slates, same statuses, same `422`s.
> `cadenceFlexibility` defaults to `NONE`, `cadenceAlternatives` comes back
> empty, and `ALTERNATIVE_CADENCE` is unreachable. **You cannot be broken by
> this change without asking for it.**

### Request fields

All seven are optional, and all seven exist on both `/availability/package-slate`
and `/availability/package-options`:

| Field | Type | Default | What it does |
| - | - | - | - |
| `cadenceFlexibility` | `"NONE"` \| `"FALLBACK"` \| `"ALWAYS"` | `"NONE"` | The master switch. `NONE` is today's behavior. `FALLBACK` returns `cadenceAlternatives` **only when the requested cadence yields nothing**. `ALWAYS` returns them alongside a successful `primarySlate` too, so you can offer "…or twice a week". |
| `guaranteeSlate` | `boolean` | `false` | Try harder before giving up — adds the direct-fill floor below. Implies `cadenceFlexibility: "FALLBACK"`, so setting this alone is enough. |
| `maxCadenceAlternatives` | integer `0`–`10` | `3` | Cap on entries in `cadenceAlternatives`. Ignored when flexibility is `NONE`. |
| `allowWeekdaySubstitution` | `boolean` | `true` | Whether a relaxed cadence may **drop** a weekday you asked for. Set `false` when the requested day is non-negotiable (the client is only home on Fridays) — the engine may then only *add* days, never swap them. |
| `minGapDays` | integer `0`–`90` | *(none)* | Minimum whole days between consecutive sessions **in the direct fill** (`guaranteeSlate`) only — not applied to any cadence-ladder rung in `cadenceAlternatives`. Use it to stop a direct fill from stacking sessions on back-to-back days. |
| `maxSessionsPerWeek` | integer `1`–`14` | *(none)* | Cap on sessions per **Monday-anchored** calendar week **in the direct fill** (`guaranteeSlate`) only — no rung in `cadenceAlternatives` is filtered by it, so a `FALLBACK`/`ALWAYS` response can still return a denser week than this cap. |
| `sessionsPerWeek` | integer `1`–`14` | *(none)* | A frequency **target**, independent of which weekdays — "twice a week". Distinct from `maxSessionsPerWeek`, which is a **cap**. Steers which cadences are offered and in what order; also stands in as the direct-fill cap when no `maxSessionsPerWeek` was given. |

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](#schedule-preferences-daysofweek-and-excludedates).

### What comes back

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

### Worked example

A supplier works **Mon–Fri, 09:00–17:00**, `America/Toronto`, on a schedule
that runs **2026-07-06 → 2026-08-03** — about four weeks. The client wants an
**8-session package** on Fridays. Eight Fridays would run to late August;
the schedule ends after the fourth. So the requested cadence is unfillable
even though the supplier is demonstrably available.

Send this body to `POST /availability/package-slate`:

```json theme={null}
{
  "packageId": "pkg_01kv7n10k0fnptwk81wkm59vj7",
  "locationId": "loc_01kv60qgs4e4nbjhzradnqtj0h",
  "timezone": "America/Toronto",
  "lookAheadStartDate": "2026-07-06T00:00:00-04:00",
  "rrule": "FREQ=WEEKLY;BYDAY=FR;COUNT=8",
  "cadenceFlexibility": "FALLBACK"
}
```

With `cadenceFlexibility` omitted (or `"NONE"`), that request is a **`422`
`NO_COMPLETE_SLATE`** — unchanged, and still the default. With `"FALLBACK"`,
the same request returns a **`200`**, and the response carries a complete
eight-session plan on **Mondays and Fridays**:

```json theme={null}
{
  "status": "ALTERNATIVE_CADENCE",
  "reason": "no complete slate at the requested cadence; returning alternative cadences",
  "requestedCadence": "FREQ=WEEKLY;BYDAY=FR;COUNT=8",
  "primarySlate": null,
  "alternates": [],
  "partial": null,
  "cadenceAlternatives": [
    {
      "slateId": "slate_01kx16ejsqffc9rbgdcc591w2p",
      "supplierId": "sup_01kv60qgnef2kt3pvqgwmkbzfr",
      "completeness": "COMPLETE",
      "sessionsRequested": 8,
      "sessionsFilled": 8,
      "matchScore": 0.5,
      "matchComponents": { "startDate": 1, "cadence": 0 },
      "cadenceRrule": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8",
      "matchesRequestedCadence": false,
      "cadenceRelaxation": "DAYS_ADDED",
      "cadenceDistance": 2,
      "cadenceSummary": {
        "requested": 1,
        "peak": 2,
        "average": 2,
        "byWeek": [
          { "weekStart": "2026-07-06", "sessions": 2 },
          { "weekStart": "2026-07-13", "sessions": 2 },
          { "weekStart": "2026-07-20", "sessions": 2 },
          { "weekStart": "2026-07-27", "sessions": 2 }
        ]
      },
      "slots": []
    }
  ]
}
```

(Abridged: `suggestionRequestId`, `resolvableUntil` and the remaining two
alternatives are omitted, and `slots[]` is collapsed as elsewhere on this
page.) `matchScore` is `0.5`, not `1`: `DAYS_ADDED` is a frequency change the
request didn't authorise, so `cadence` scores `0` and drags the mean down
from the `startDate` component's `1`.

The eight sessions land on **Jul 6, 10, 13, 17, 20, 24, 27 and 31** — all
inside the supplier's schedule, where eight Fridays would have needed until
late August. `cadenceRelaxation` is `DAYS_ADDED` because Friday was *kept*
and one weekday was added; `cadenceDistance: 2` ranks it as the closest
answer available.

`cadenceSummary` reads that same plan back as a cadence: `requested: 1`,
because the `rrule` you sent named one weekday, against a `peak` of `2` — the
number to put in front of a client. Here the plan runs at exactly two a week
in all four of its weeks, so `average` matches `peak`; the two only part
company when a week comes up short.

> [!NOTE]
>
> Monday is chosen, not Wednesday or Thursday, because when the engine adds a
> weekday it **maximises the spacing between sessions**. `{MO, FR}` leaves gaps
> of 4 and 3 days; `{TH, FR}` would leave 1 and 6. Sessions spread evenly
> across the week beat sessions bunched against the day you asked for.

Here the default `maxCadenceAlternatives: 3` means three plans come back —
`MO,FR` first, then progressively denser ones. Render them as a choice
("we can't do 8 Fridays, but we can do 8 sessions on Mondays and Fridays")
rather than picking one silently.

### Asking for a frequency: "twice a week, any day"

A frequency picker collects "twice a week" with no weekday preference.
`rrule` can't express that on its own — it names specific weekdays — and
`daysOfWeek` is a hard filter, so naming days there would rule every other
day out.

Send `sessionsPerWeek` alongside a starting-point `rrule` instead. Here's a
complete body for `POST /availability/package-slate`: `rrule` is
**required** on this endpoint, so the two weekdays in it are a starting
point, not a constraint — `sessionsPerWeek` states the real target, and
`allowWeekdaySubstitution` (default `true`) lets the engine move the days to
hit it:

```json theme={null}
{
  "packageId": "pkg_01kvr4cgb3esg8hxx32kwhre7g",
  "locationId": "loc_01kv60qgs4e4nbjhzradnqtj0h",
  "timezone": "America/Toronto",
  "lookAheadStartDate": "2026-07-06T00:00:00-04:00",
  "rrule": "FREQ=WEEKLY;BYDAY=MO,TH;COUNT=8",
  "sessionsPerWeek": 2,
  "cadenceFlexibility": "ALWAYS"
}
```

**Omit `daysOfWeek` entirely.** Sending it would make `MO,TH` a hard filter
and, on top of that, withdraw the `cadence` component's substitution
exemption (see [How well a slate matches](https://docs.gomarketbox.com/resources/suggestions.md#how-well-a-slate-matches-matchscore-and-matchcomponents)).
On `/availability/package-options`, `rrule` is optional; omit it there and
the cadence is synthesised per package from its credit count, with
`sessionsPerWeek` still steering.

`sessionsPerWeek` is always *scored* — `matchComponents.sessionsPerWeek`
comes back on any slate — but it only *steers which slates get built* when
cadence relaxation actually runs. That means `cadenceFlexibility: "ALWAYS"`,
or `"FALLBACK"` once the requested cadence yields nothing, or
`guaranteeSlate: true` (which promotes `NONE` to `FALLBACK`). On the default
`"NONE"`, the `rrule` fixes the schedule completely, and the target is
scored but changes nothing about which slates come back.

Where to read the answer — and the trap that pairs with the point above:

* With `"ALWAYS"` and a fillable requested cadence: `status: "OK"`, the
  answer is `primarySlate`, and `cadenceAlternatives` carries the denser
  options alongside it.
* When the requested cadence can't be met but a relaxed one can:
  **`status: "ALTERNATIVE_CADENCE"`, `primarySlate` is `null`, and the
  answer is `cadenceAlternatives[0]`** — already ordered closest-first, with
  the frequency target ranked ahead of raw cadence distance. This is a
  `200`, not a failure. **A client that reads only `primarySlate` concludes
  there's no availability when a bookable plan is sitting right there** —
  see the warning under [Status values](#status-values), which already
  makes the "don't branch on `primarySlate` alone" point.
* Take `cadenceAlternatives[0]` rather than re-sorting by `matchScore` — see
  the [warning in Suggestions](https://docs.gomarketbox.com/resources/suggestions.md#how-well-a-slate-matches-matchscore-and-matchcomponents):
  a three-a-week plan ties a two-a-week one against a target of `2`, so only
  the order tells them apart.

### `guaranteeSlate` and the direct fill

When *every* relaxed cadence also fails — the supplier works no Fridays at
all, say, and you've set `allowWeekdaySubstitution: false` so Friday can
never be dropped — `guaranteeSlate: true` adds one last floor: a **direct
fill**. All N sessions are picked straight from the supplier's real openings,
one per day, at the most consistent start time available, following **no
recurrence rule at all**.

Direct-fill slates are recognisable by two fields:

```json theme={null}
{
  "cadenceRrule": null,
  "cadenceRelaxation": "DIRECT_FILL"
}
```

> [!WARNING]
>
> **`guaranteeSlate` guarantees flexibility of *cadence*, not of *capacity*.**
> The name promises more than it delivers if you read it quickly. A supplier
> who simply doesn't have N open days still yields no complete plan — there is
> no cadence clever enough to invent time that isn't there. When that happens
> the under-filled plan is surfaced (or not) through `partial`, governed by the
> project's `suggestionConfig.allowPartialPackages` setting, exactly as it is
> today. `guaranteeSlate` does not override that setting, and it is not a
> guarantee that you always get a slate.

## Schedule preferences: `daysOfWeek` and `excludeDates`

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

### `daysOfWeek` is a hard filter, not a preference

`daysOfWeek` is an **allow-list** of weekdays sessions may fall on, using the
convention `0 = Sunday … 6 = Saturday`:

```json theme={null}
{ "daysOfWeek": [1, 2, 3, 4, 5] }
```

It's enforced **before** the planner ever looks at the supplier's
availability: a weekday you leave out is removed from the pool the engine
plans against, not filtered out of a result afterward. That has one
consequence worth stating plainly — **[cadence relaxation](#cadence-relaxation)
cannot reintroduce a day `daysOfWeek` excludes.** Every fallback cadence
`cadenceFlexibility` can produce, including the
[direct fill](#guaranteeslate-and-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.

> [!WARNING]
>
> **`daysOfWeek` is an allow-list, not a block-list.** If your UI collects
> exceptions the other way around — "No Sun / No Mon" chips a client toggles
> *on* to exclude those days — you must invert the selection before calling
> the API: send the days that remain (`[2, 3, 4, 5, 6]`), not the two the
> client excluded. Sending the excluded days directly restricts the plan to
> almost nothing instead of almost everything — the obvious integration bug
> here.

Omit `daysOfWeek` entirely to allow any day.

> [!NOTE]
>
> **Same field name, opposite behaviour on `/availability/suppliers`.** This
> hard-filter behaviour is specific to `package-slate` and `package-options`.
> On [`POST /availability/suppliers`](https://docs.gomarketbox.com/guides/search-suppliers-by-availability#rank-suppliers-by-fit-availabilitymatch),
> `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:

```json theme={null}
{ "excludeDates": ["2026-08-20", "2026-08-21", "2026-08-22"] }
```

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

### The synergy: a blackout doesn't have to mean a refusal

Blacking out enough dates to make the *exact* requested cadence unfillable
used to mean the request came back a flat `422 NO_COMPLETE_SLATE` — even if
the supplier had plenty of other open time. With `cadenceFlexibility` opted
in, the same blackout can now produce a **relaxed-cadence plan** instead of
a refusal.

Take the same supplier as the [worked example](#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:

```json theme={null}
{
  "packageId": "pkg_01kvr4cgb3esg8hxx32kwhre7g",
  "timezone": "America/Toronto",
  "lookAheadStartDate": "2026-07-06T00:00:00-04:00",
  "rrule": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8",
  "cadenceFlexibility": "FALLBACK"
}
```

Without any exclusions, that cadence fills cleanly — eight sessions on Jul
6, 10, 13, 17, 20, 24, 27, and 31. Now black out the third week's Monday and
Friday:

```json theme={null}
{ "excludeDates": ["2026-07-20", "2026-07-24"] }
```

That removes 2 of the 8 occurrences the exact cadence needs. The rest of
the \~4-week schedule has only 7 more Monday/Friday slots to draw from (4
Mondays + 3 Fridays — the next Friday, Aug 7, falls after the schedule
ends), one short of the 8 requested. **No occurrence set of the exact
`MO,FR` cadence can complete, from any start date** — every prior version of
this endpoint would `422` here.

With `cadenceFlexibility: "FALLBACK"` set, the response instead comes back:

```json theme={null}
{
  "status": "ALTERNATIVE_CADENCE",
  "reason": "no complete slate at the requested cadence; returning alternative cadences",
  "suggestionRequestId": "sugreq_01kx16ej7pe4r9da74adf6m4h0",
  "resolvableUntil": "2026-07-07T12:00:00.000Z",
  "primarySlate": null,
  "alternates": [],
  "partial": null,
  "cadenceAlternatives": [
    {
      "slateId": "slate_01kx16ejsqffc9rbgdcc591w2p",
      "supplierId": "sup_01kv60qgnef2kt3pvqgwmkbzfr",
      "completeness": "COMPLETE",
      "sessionsRequested": 8,
      "sessionsFilled": 8,
      "startTimeConsistencyPercent": 100,
      "matchScore": 0.5,
      "matchComponents": { "startDate": 1, "cadence": 0 },
      "totalTravelTimeMins": 0,
      "cadenceRrule": "FREQ=WEEKLY;BYDAY=MO,TU,WE,FR;COUNT=8",
      "matchesRequestedCadence": false,
      "cadenceRelaxation": "DAYS_ADDED",
      "slots": []
    }
  ],
  "requestedCadence": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
}
```

(`cadenceAlternatives[0].slots` abridged to `[]` here, the same convention
as [Anatomy of a slate](#anatomy-of-a-slate) above. `cadenceDistance` — present
on a real response here, since it's stamped whenever relaxation was requested —
and [`cadenceSummary`](https://docs.gomarketbox.com/resources/suggestions#how-often-a-plan-runs-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](#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.

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

```ts theme={null}
// Map each resolved slot to a `sessions[]` entry — VERBATIM, except PHYSICAL
// coordinates (see the warning below).
function transcribeSlot(slot: PackageSlot) {
  return {
    supplierId: slot.supplierId,
    bookingStartUtc: slot.bookingStartUtc,
    bookingEndUtc: slot.bookingEndUtc,
    bookingTz: slot.bookingTz,
    locationType: slot.locationType,
    locationId: slot.locationId,
    // A PHYSICAL slot carries the Location's coordinates, but a PHYSICAL
    // session must not send them — the booking derives them from the Location.
    ...(slot.locationType !== 'PHYSICAL' && {
      latitude: slot.latitude,
      longitude: slot.longitude,
    }),
    address: slot.address,
    services: [{ serviceId: slot.serviceId, offeringId: slot.offeringId }],
  };
}

const sessions = primarySlate.slots.map(transcribeSlot);

// Mint the key ONCE per booking attempt, and resend this same key if you retry
// the call. A new key on every call can't make a retry safe.
const idempotencyKey = crypto.randomUUID();

await fetch(`${MARKETBOX_API_URL}/v1/projects/${MARKETBOX_PROJECT_ID}/orders/${orderId}/package-bookings`, {
  method: 'POST',
  headers: { 'x-api-key': MARKETBOX_API_KEY, 'content-type': 'application/json' },
  body: JSON.stringify({
    orderItemId,
    idempotencyKey,
    atomicity: 'all_or_nothing',
    sessions,
  }),
});
```

> [!WARNING]
>
> **Copy each slot verbatim — do not re-derive locations.** A `TRAVEL_ZONE`
> slot's `locationId` is the supplier's *resolved travel zone*, computed by
> the slate engine specifically for that supplier and location. Recomputing
> it yourself (e.g. re-resolving from raw `lat`/`lng`) can silently select the
> wrong zone and mis-place the booking by a meaningful distance. Take the slot
> fields as-is; only omit or reorder whole sessions, never recompute their
> contents.
>
> The one field to drop is `latitude`/`longitude` on a `PHYSICAL` slot. The
> slot carries the Location's coordinates, but a `PHYSICAL` session that sends
> them is a `400` with `PHYSICAL bookings derive coordinates from the Location
>   — do not pass latitude/longitude`, and nothing is booked.

`slotId`, `sessionIndex`, `travelTimeMins`, `capacity`, and the deprecated
`reservationStatus` are **not** part of a session entry — they're slate
metadata, not booking input. Only the fields listed above go into
`sessions[]`.

Provide **exactly one** of `sessions`, `slateId`, or `slotIds` on
`POST .../package-bookings` — sending more than one (or none) is a `400
VALIDATION_ERROR`.

## Path B: hold, then convert

Both `slateId` and Path A book immediately. If you need to **hold the
sessions while the client pays** — a timed checkout — don't book at all:
hold the slate, take payment, then convert the hold into bookings.

Holds are no longer a package-only concept, and they no longer live under
`/suggestions`. A hold is a standalone claim on supplier time
(`POST /v1/projects/{projectId}/holds`), and it takes **exactly one** of
`intervals` (explicit supplier time — this is how you hold a *single*
session, with no package or slate anywhere), `slateId` (every slot of the
slate you just built), or `slotIds` (a cherry-picked subset). Convert is a
single endpoint for both shapes. The whole lifecycle — hold, heartbeat,
convert, release, and the `SLOT_HELD` error you get if you try to book held
time directly — is covered in
[Hold slots during checkout](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md).

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

> [!WARNING]
>
> A live hold blocks the time it claims: the slot stops being returned by
> availability search, and a direct `POST .../package-bookings` over it fails
> with `409 SLOT_HELD` — **even when the hold is your own**. If you hold, you
> convert. See [Concurrency](https://docs.gomarketbox.com/concepts/concurrency.md).

## Reference

### Endpoints used in this guide

| Endpoint | Method | Auth | Description |
| - | - | - | - |
| `/v1/projects/{projectId}/availability/search` | `POST` | `x-api-key` | Single-session slot search. Full reference: [Availability](https://docs.gomarketbox.com/resources/availability.md). |
| `/v1/projects/{projectId}/availability/time-slots` | `POST` | `x-api-key` | Direct engine invocation. Full reference: [Availability](https://docs.gomarketbox.com/resources/availability.md). |
| `/v1/projects/{projectId}/availability/suppliers` | `POST` | `x-api-key` | Paginated suppliers, each with open slots grouped by local day. Full reference: [Availability](https://docs.gomarketbox.com/resources/availability.md). |
| `/v1/projects/{projectId}/availability/package-slate` | `POST` | `x-api-key` | Build an N-session slate for a package from one supplier. `422` only when `primarySlate`, `partial` **and** `cadenceAlternatives` are all empty — a bookable `cadenceAlternatives` makes it a `200`. |
| `/v1/projects/{projectId}/availability/package-options` | `POST` | `x-api-key` | Plan **every** ACTIVE package of a service in one call. Always `200` — an unbookable package carries its own `status` + `reason` instead of failing the request. Accepts the same cadence-relaxation fields. |
| `/v1/projects/{projectId}/orders/{orderId}/package-bookings` | `POST` | `x-api-key` | Book via `sessions` (Path A), `slateId`, or `slotIds` — exactly one. |
| `/v1/projects/{projectId}/holds` | `POST` | `x-api-key` | Hold supplier time — `intervals`, `slateId`, or `slotIds` (exactly one). Returns `reservationId` + `heldUntil`. See [Hold slots during checkout](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md). |
| `/v1/projects/{projectId}/holds/{reservationId}/convert` | `POST` | `x-api-key` | Convert a hold into confirmed bookings. Idempotent — safe to retry. |
| `/v1/projects/{projectId}/holds/{reservationId}/release` | `POST` | `x-api-key` | Release a hold. Idempotent — always `200`. |
| `/v1/projects/{projectId}/suggestions/slots/{slotId}/reschedule` | `POST` | `x-api-key` | Move one slot of a stored slate to a new time before anything is booked. Full reference: [Suggestions](https://docs.gomarketbox.com/resources/suggestions.md#rescheduling-a-slot). |

For suggestion requests, slates and slots as objects, and the 24-hour window
they stay usable in, see [Suggestions](https://docs.gomarketbox.com/resources/suggestions.md). To let a
client move one session of a slate before you hold or book it, see
[Let clients adjust a proposed slate](https://docs.gomarketbox.com/guides/adjust-a-proposed-slate.md). For the hold
object, see [Holds](https://docs.gomarketbox.com/resources/holds.md).

### Configuration

| Value | Env var | Browser? |
| - | - | - |
| API key | `MARKETBOX_API_KEY` | **No** (server-only) |
| API base URL | `MARKETBOX_API_URL` | **No** (BFF-only) |
| Project id | `MARKETBOX_PROJECT_ID` | **No** (BFF-only) |

### Errors and edge cases

| Scenario | `code` | Status | Resolution |
| - | - | - | - |
| `rrule` has no bounded `COUNT` | `VALIDATION_ERROR` | `400` | Add a positive `COUNT`, e.g. `FREQ=WEEKLY;BYDAY=MO;COUNT=8`. |
| `lookAheadStartDate` has a `Z` suffix instead of a numeric offset | `VALIDATION_ERROR` | `400` | Use a numeric `±HH:MM` offset, e.g. `-04:00`. |
| `timezone` is an abbreviation or offset (`EST`, `GMT+5`) rather than an IANA identifier | `VALIDATION_ERROR` | `400` | Send an IANA zone, e.g. `America/Toronto`. See [Timezones](https://docs.gomarketbox.com/concepts/timezones.md#valid-timezones). |
| Cadence needs more than 120 days to fit the package's `creditCount` sessions, and `cadenceFlexibility` is `NONE` | `NO_COMPLETE_SLATE` | `422` | `reason` names the exact window required. Use a denser cadence (more days per week), fewer sessions per call, or set `cadenceFlexibility` — with flexibility on, the window **clamps to 120 days and the engine runs**, since a denser cadence needs a shorter window. |
| No availability at all for the requested window/location | `NO_AVAILABILITY` | `422` | Try a different location, timezone, or `lookAheadStartDate`. |
| No complete single-supplier slate under the project's supplier policy | `NO_COMPLETE_SLATE` | `422` | Check `alternates`/`partial` in the response first — they may still be usable. Set `cadenceFlexibility` to also get complete plans at a denser cadence in `cadenceAlternatives`. Otherwise widen the window or location. |
| Provided more than one (or none) of `sessions` / `slateId` / `slotIds` on booking or holding | `VALIDATION_ERROR` | `400` | Provide exactly one. |
| The referenced slate/slot doesn't exist, has no slots, or is past its 24-hour resolvable window (**holding only**) | `SLATE_NOT_FOUND` / `SLOT_NOT_FOUND` / `SUGGESTION_EXPIRED` | `409` | Rebuild the slate with `POST /availability/package-slate` and hold the fresh one. |
| Chosen slot went stale between building a slate and booking it directly (`slateId`/`slotIds`, no hold) | `SLOT_NO_LONGER_BOOKABLE` | `409` | The response includes `freshSuggestions` — rebuild from it. Covered in depth in [Create a package booking](https://docs.gomarketbox.com/guides/create-a-package-booking.md#reference). |
| The time is claimed by a live hold — including your own, if you tried to book it directly instead of converting | `SLOT_HELD` | `409` | The first `conflicts[]` entry with `claimType: "HOLD"` names the hold in `reservationId`. Convert it, or offer another slot. See [Hold slots during checkout](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md#handling-a-held-slot). |
| The time is claimed by a confirmed booking | `SLOT_BOOKED` | `409` | Rebuild the slate — the supplier is taken. |
| More than 15 sessions with `atomicity: "all_or_nothing"` (applies to direct booking and convert alike) | `PACKAGE_SLATE_TOO_LARGE_FOR_ATOMIC` | `422` | Use `atomicity: "best_effort"` (requires `suggestionConfig.allowPartialPackages`), or book/hold a smaller slate. |
| `best_effort` requested but the project hasn't enabled it | `BEST_EFFORT_NOT_ENABLED` | `422` | Stay with `all_or_nothing` (≤15 sessions), or ask the project to enable `suggestionConfig.allowPartialPackages`. |

> [!WARNING]
>
> **The granular stale codes above (`SLATE_NOT_FOUND`, `SLOT_NOT_FOUND`,
> `SUGGESTION_EXPIRED`) are returned verbatim only by `POST /holds`.** At
> booking time — `POST .../package-bookings` by `slateId`/`slotIds` — every
> one of these same stale conditions is collapsed to a single
> `code: "SLOT_NO_LONGER_BOOKABLE"` (the `message` still names the specific
> cause). Branch on the distinct codes only when you're calling the holds
> endpoint; for direct booking, branch on `SLOT_NO_LONGER_BOOKABLE` alone.

See [Errors](https://docs.gomarketbox.com/concepts/errors.md) for the full envelope and code list,
[Concurrency](https://docs.gomarketbox.com/concepts/concurrency.md) for supplier-time conflicts, and
[Create a package booking](https://docs.gomarketbox.com/guides/create-a-package-booking.md#reference) 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.


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