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

> Find when and where suppliers can fulfill a service — suggested slots, open slots, and recurring patterns.

**Availability** is the public face of the MarketBox clustering engine.
Given a service, a location, and a window of time, it returns the slots
a supplier can realistically be booked into — accounting for existing
bookings, schedules, and travel time between jobs.

There are five endpoints, all project-scoped and authenticated with the
`x-api-key` header. The first three answer "when is someone free?" for a
**single session**; the last two build **complete N-session plans** for a
package:

| Endpoint | Use it when |
| - | - |
| `POST .../availability/search` | You have a service + offering + location and want the API to find suppliers and slots from project data. |
| `POST .../availability/time-slots` | You already have suppliers + their bookings and want to run the engine directly, passing everything in the body. |
| `POST .../availability/suppliers` | You want the same availability **grouped by supplier** — a paginated list of supplier profiles, each with open slots bucketed by local day. |
| `POST .../availability/package-slate` | You want a **complete N-session plan** for one package, from one supplier, built from a recurrence rule. |
| `POST .../availability/package-options` | You want **every** ACTIVE package of a service planned in one call, each with its own ready-to-book `slateId`. |

> [!NOTE]
>
> Every endpoint on this page is authenticated with the `x-api-key` header,
> not `Authorization`. See [Authentication](https://docs.gomarketbox.com/concepts/authentication.md).

> [!NOTE]
>
> The two package endpoints have package-specific anatomy — slate and slot
> shapes, cadence rules, the 120-day look-ahead ceiling, cadence relaxation,
> and the hold/convert path. They're summarised below and documented in full
> in [Availability and slates](https://docs.gomarketbox.com/guides/availability-and-slates.md).

## Search (who-is-available)

```
POST /v1/projects/{projectId}/availability/search
```

You pass a service, an offering, and a discovery location; the API
resolves matching suppliers from project data and returns suggested
slots, open slots, and (for recurring requests) recurrence patterns.

**Required:** `serviceId`, `offeringId`, and **either** `locationId`
**or** both `lat` and `lng`. Omitting the location entirely is a `400`.

| Field | Notes |
| - | - |
| `serviceId` | Required. The service to book. |
| `offeringId` | Required. The offering under that service. |
| `locationId` | Stored location id — or pass `lat` + `lng` instead. |
| `lat`, `lng` | Discovery coordinates (travel-zone branch). |
| `durationMinutes` | Override the offering duration (FLEXIBLE offerings). |
| `lookAheadStartDate` | ISO start of the search window. |
| `lookAheadDays` | Window length in days. |
| `timezone` | IANA identifier (`America/Toronto`) for the returned local times. Abbreviations and offsets (`EST`, `GMT+5`) are a `400`. |
| `distanceUnit` | `km` or `mi`. |
| `interval` | Open-slot granularity in minutes. |
| `timeSuggestionsLimit` | Cap on suggested slots returned. |
| `sortBy` | `leastTravelTime` or `nearestDate`. |
| `daysOfWeek` | Allow-list of weekdays a slot may fall on (`0 = Sunday … 6 = Saturday`). Omit for any day. See the note below. |
| `skills` | Supplier skill ids. A supplier must hold **all** of them to be considered. Omit for no skill filter. |

> [!NOTE]
>
> **`daysOfWeek` is a hard allow-list, not a preference.** A weekday you
> leave out is removed from the pool before the engine searches — no
> matching slot can land on it. If your UI collects the inverse (exception
> chips like "No Sundays" the client toggles *on*), invert the selection
> before sending it: pass the days that remain allowed, not the ones the
> client excluded.
>
> `excludeDates` (individual LOCAL blackout dates, no range form) is a
> related field, but it isn't part of this endpoint's request — it's
> specific to `package-slate` and `package-options`. See
> [Availability and slates](https://docs.gomarketbox.com/guides/availability-and-slates.md#schedule-preferences-daysofweek-and-excludedates).

The response envelope:

```json theme={null}
{
  "status": "success",
  "searchId": "<the search's id>",
  "engineEnabled": true,
  "timeSlots": [
    { "supplierId": "sup_…", "timeSlotDateAndTime": "2026-06-23T10:00:00-04:00", "timeSlotStartUtc": "2026-06-23T14:00:00.000Z", "travelType": "TO-NEXT-BOOKING", "travelTimeMins": 8 }
  ],
  "openSlots": [ { "supplierId": "sup_…", "timeSlotId": "…", "timeSlotDateAndTime": "2026-06-23T09:15:00-04:00", "timeSlotStartUtc": "2026-06-23T13:15:00.000Z" } ],
  "timezone": "America/Toronto",
  "supplierZones": { "sup_…": "America/Toronto" },
  "suppliers": [ { "supplierId": "sup_…", "position": 0 } ],
  "errors": []
}
```

No matching suppliers returns the same envelope with empty
`timeSlots` / `openSlots` and `errors: []`.

> [!WARNING]
>
> **A failed search is still a `200`.** The engine reports failures as strings
> in `errors[]`, not as an HTTP error. Empty slots with a non-empty `errors`
> means the search broke, not that nobody is free. Check `errors` before you
> tell a client there is no availability. `/availability/suppliers` behaves
> the same way.

> [!WARNING]
>
> **Check `engineEnabled` before you say nobody is free.** It is `false` when
> the project has switched its scheduling engine off. The engine then doesn't
> run, so `timeSlots` is empty because it wasn't computed, not because nobody
> is free. `openSlots` is unaffected.

`searchId` identifies this search; it is also the `X-MB-Search-Id` header.
`suppliers` lists each supplier that appears in `timeSlots` or `openSlots`,
with its `position`: the 0-based rank of its first slot, `timeSlots` first.
Keep the `searchId` for the session, and report what you draw with it. See
[Report site events](https://docs.gomarketbox.com/guides/report-site-events.md#search-ids).

### Slot times and zones

Every slot in `timeSlots[]` and `openSlots[]` carries the same instant twice:

| Field | Meaning |
| - | - |
| `timeSlotStartUtc` | The slot start as a UTC instant, always `Z`-suffixed. **Use this as the booking anchor** — it is what `bookingStartUtc` expects, and it needs no zone-aware parsing. |
| `timeSlotDateAndTime` | The same instant as a local clock in the response `timezone`, with that zone's offset **at that instant** — so a slot on the far side of a daylight-saving change carries the offset for its own day. For display. |

The envelope's `timezone` is the zone actually used to render
`timeSlotDateAndTime` and to bucket days: the request `timezone`, or the
project default when you sent none. If your code reads the clock digits
rather than parsing the whole string, send `timezone` explicitly.

`supplierZones` maps each supplier that appears in the slot arrays to their
own profile zone. Use it as the `bookingTz` for a **virtual** booking with no
service location — the location's zone wins when there is one, then the
supplier's, then the project default. A supplier missing from the map has no
profile zone; fall back to the project default.

### Search ids on every availability route

Every route on this page returns a `searchId`, in the body and in the
`X-MB-Search-Id` header:

* `/suppliers` — the same `searchId` on every page (the cursor keeps it), and
  each supplier a `position`, continuous across pages.
* `package-slate` — a `searchId`, and each slate a `position` across the whole
  response.
* `package-options` — a `searchId`, and each slate a `position` within its
  package.
* `time-slots` — a `searchId`, but nothing from it is logged for insights.

You may tag any of them with two optional headers, stored for insights and
never acted on: `X-MB-Session-Key` (an opaque session key, at most 64
characters) and `X-MB-Client-Kind` (`browser`, `server`, `monitor` or
`loadtest`).

## How offered times are worked out

These rules apply to `/search`, `/suppliers` and `/time-slots`.

### Travel fields on a slot

Each suggested slot in `timeSlots[]` says how it was placed:

| Field | Meaning |
| - | - |
| `travelType` | What the slot was placed against: `FROM-PREVIOUS-BOOKING`, `TO-NEXT-BOOKING`, `SAME-LOCATION-AS-PREVIOUS`, `SAME-LOCATION-AS-NEXT`, `ON-EMPTY-DAY`, `FROM-START-LOCATION` or `TO-END-LOCATION`. |
| `travelTimeMins` | The drive, timed for the time of day it happens (with traffic). It never includes a service's `bufferBeforeStartMinutes`. |
| `travelDistance` | The distance of the drive the slot was placed on, in `distanceUnit`. `null` means the drive is unknown. |

Accept every `travelType` value. The start and end values appear only when
the project uses [start and end of day locations](#start-and-end-of-day-locations).

### Split shifts

When a supplier's day has a break, each block of the day is treated on its
own. A break comes from two time ranges on one weekday, two schedules on one
date, or blocked time in the middle of a range.

Each block offers its own first and last time. On an empty day of 9:00–13:00
and 15:00–18:00, a 30-minute service is offered at 9:00, 12:30, 15:00 and
17:30. Ranges that touch, such as 9:00–13:00 and 13:00–17:00, are one block.

A `FROM-PREVIOUS-BOOKING` or `TO-NEXT-BOOKING` time can be on the other side
of a break. Don't assume it comes right after, or right before, the booking
it refers to. `travelTimeMins` still gives the real drive.

### Open slots leave time to drive

Open slots leave time for the supplier to drive from the booking before and
to the booking after. That drive is an estimate from the straight-line
distance, rounded up to 5 minutes. A booking within 50 m of the requested
place counts as the same place, so back-to-back times there are still
offered. Your project's open-slot buffer applies on top.

Where roads are slower than the estimate, an open slot can still need an
override when staff book it.

### Drive times account for traffic

Each drive is timed for the time of day it happens. A drive at rush hour
takes longer, so rush-hour times can move later or disappear. The supplier's
maximum travel time is checked against the drive with traffic. Don't cache
drive times across times of day.

### A buffer before the service

A service's `bufferBeforeStartMinutes` (0–120) leaves a gap before a job of
that service in suggested times. It isn't busy time, and it isn't part of
`travelTimeMins`. A booking made at a specific time is never refused because
of it.

### Start and end of day locations

A project can let a supplier's schedule set where their working day starts
and ends. It's off by default. See
[Start and end of day locations](https://docs.gomarketbox.com/guides/supplier-portal-availability.md#start-and-end-of-day-locations).

Once it's on and a supplier has set locations:

* The first and last times of a day can shift, because the drive from the
  start location and to the end location counts.
* Slots can carry `FROM-START-LOCATION` or `TO-END-LOCATION`.
* A slot with `travelDistance: null` was placed against a drive that couldn't
  be routed. On such a slot, `travelTimeMins: 0` doesn't mean there's no
  travel.
* No availability response contains a supplier's start or end address or
  coordinates.

### What `errors[]` can contain

`errors[]` entries are strings. A supplier named in one has a partial or
empty result. That doesn't mean they have no availability.

| Entry starts with | Meaning |
| - | - |
| `SupplierError (supplierId: sup_…): <error name>: route request failed` | A drive this supplier needed couldn't be routed. The supplier has no slots in this result. |
| `SupplierError (supplierId: sup_…): Booking bk_… has coordinates outside the valid range` | One of this supplier's bookings has invalid saved coordinates. Only this supplier is affected. Fix the booking's address. |
| `SupplierWarning: a start or end drive could not be routed` | At least one of this supplier's times was left out because a start or end drive couldn't be routed. The rest of their times are valid. |

## Recurring search

To find a repeating slot pattern, set `bookingType` to `recurring`
and pass an `rrule`. The recurring branch returns **pattern objects**
(`mostAvailableStartTime`, `startTimeConsistencyPercent`) in
`timeSlots[]` rather than individual slots.

Recurring requests have one strict requirement, a `400` if not met:

> [!WARNING]
>
> **`rrule` must include a bounded `COUNT`** (e.g.
> `FREQ=WEEKLY;BYDAY=TU;COUNT=3`). The builder expands each occurrence
> set to `COUNT` dates and needs a slot on every one; an unbounded rule
> defaults to 10 occurrences and almost always returns nothing.

`lookAheadStartDate` is any ISO-8601 instant — a `Z` suffix and a numeric
offset are equally valid. The window and the recurrence anchor are resolved
on the **local date in the request `timezone`**, so a midnight-UTC start
against a zone west of Greenwich anchors on the previous local day. A value
that does not parse is a `400`.

```json theme={null}
{
  "serviceId": "srv_…",
  "offeringId": "off_…",
  "lat": 45.4215,
  "lng": -75.6972,
  "bookingType": "recurring",
  "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU;COUNT=3",
  "daysOfWeek": [2],
  "lookAheadStartDate": "2026-06-23T04:00:00Z",
  "lookAheadDays": 16,
  "timezone": "America/Toronto"
}
```

## Time-slots (direct engine)

```
POST /v1/projects/{projectId}/availability/time-slots
```

The lower-level endpoint. Instead of resolving suppliers from project
data, you pass them in: their availability, existing bookings, and an
engine config. Use it when you already hold the scheduling state and
just want the engine's clustering + travel-time logic.

The body is `{ config, suppliers[] }`:

* **`config`** — engine settings: `targetGeoLocation`,
  `targetServiceDurationMins`, `lookAheadStartDate` / `lookAheadEndDate`,
  `distanceUnit`, `sortBy`, `timezone`, and so on.
* **`suppliers[]`** — each with `supplierId`, `maxTravelTimeMins`,
  `bufferTimeMins`, an `availability[]` array (each with an `rrule`),
  `bookings[]`, and `blockedTime[]`.

Omitting `suppliers` is a `400`. The response adds `metrics` and `kpis`
to the slot list.

* `metrics.totalTravelTimeRequestsMade` counts the distinct drives
  (direction, place) answered for the whole request, shared across all
  suppliers. A failed or unroutable drive isn't counted.
* Each slot's `travelDistance` is the distance of the drive the slot was
  placed on.
* A recurring availability window in a zone ahead of UTC lands on the
  weekdays you wrote. For example, a Monday window at `09:00+11:00` is
  served on Mondays.
* Counts and slot distances changed on 2026-11-12. A payload captured before
  then can replay with different counts, distances and labels, and can gain
  slots.

```json theme={null}
{
  "status": "success",
  "timeSlots": [ { "supplierId": "sup_…", "travelType": "TO-NEXT-BOOKING", "travelTimeMins": 8 } ],
  "errors": [],
  "metrics": { "totalBookings": 1, "totalSuppliers": 1, "lookAheadDays": 5 },
  "kpis": { "requestOptimizationRatio": 0.42 }
}
```

## Suppliers (grouped by supplier)

```
POST /v1/projects/{projectId}/availability/suppliers
```

The same single-session availability as `/search`, pivoted: instead of flat
slot arrays you get a **paginated list of suppliers**, each with its full
profile (the same shape as `GET /suppliers`) and its open slots bucketed by
local day. Use it to render a wall of supplier cards with bookable times.

**Required:** `serviceId`, `offeringId`, and **either** `locationId` **or**
both `lat` and `lng` — the same location rule as `/search`.

Notes that catch people out:

* It returns **regular-interval open slots only** — no clustered or
  travel-optimized suggestions, and no recurrence patterns. Use `/search`
  for those.
* Suppliers that match the service and location but have **no availability**
  in the window are still returned, with `days: []`. Filter client-side if
  you only want bookable ones.
* Paginate with `limit` (max 50) plus the opaque `cursor`. `nextCursor` is
  `null` on the last page.
* Each slot carries a UTC anchor (`startUtc` / `endUtc`) **plus** `*Local`
  strings rendered in the request `timezone`, with that zone's offset at
  that instant. `startUtc` is the engine's `timeSlotStartUtc` verbatim.

### Rank suppliers by fit: `availabilityMatch`

Four new optional request fields describe the schedule you actually want,
rather than just a window to search. Three of them — plus the pre-existing
`lookAheadStartDate` — feed the `availabilityMatch` score below;
`excludeDates` instead filters the slot pool and has no score component:

| Field | Notes |
| - | - |
| `preferredTimes` | `[{ startTime: "HH:mm", endTime: "HH:mm" }]`, nullable. Ranking only — no slot is removed for falling outside a window. A window may cross midnight (`"22:00"`–`"02:00"` matches both `23:00` and `01:00`). |
| `daysOfWeek` | `0 = Sunday … 6 = Saturday`, 1–7 entries when present; omit for any day. **Ranking preference on this endpoint** — unlike the same-named field on `/availability/package-slate`, which is a hard filter. |
| `excludeDates` | Local `YYYY-MM-DD` dates, max 90, passed individually (no range form). **Removes slots** from the pool before scoring — a blacked-out date never appears in `days[]`, and has no `availabilityMatch` component. |
| `sessionsPerWeek` | Integer 1–14. A weekly-cadence preference that feeds the score; there's no package and no `COUNT` to plan against here. |

`availabilityMatch` is produced by four **scoring criteria**:
`lookAheadStartDate`, `preferredTimes`, `daysOfWeek`, and `sessionsPerWeek`.
Send any of those four and each supplier in `data[]` gains an
`availabilityMatch` object next to `supplier` and `days`:

```json theme={null}
{
  "score": 0.8035714285714286,
  "components": {
    "startDate": 0.7142857142857143,
    "timeOfDay": 0.5,
    "daysOfWeek": 1,
    "sessionsPerWeek": 1
  }
}
```

* `score` is the plain, unrounded mean of the `components` present —
  renormalised over only the criteria you sent, not divided by 4. Sending one
  preference can legitimately score a supplier `1.0`.
* `components` carries exactly one key per field you sent: `startDate` for
  `lookAheadStartDate` (present only when you explicitly send it — its
  denominator is the local dates your window actually spans, not
  `lookAheadDays`), `timeOfDay` for `preferredTimes`, `daysOfWeek` for
  `daysOfWeek`, `sessionsPerWeek` for `sessionsPerWeek`.
* Suppliers with no matching availability are still returned, with `score: 0`
  — never dropped from the page.
* `availabilityMatch` is **omitted entirely**, not `null`, when none of
  `lookAheadStartDate`, `preferredTimes`, `daysOfWeek` or `sessionsPerWeek`
  is sent. **`excludeDates` alone does not produce one** — it filters the
  slot pool instead of scoring it, so a request carrying only `excludeDates`
  gets the same response shape as before this field existed.
* Ranking only holds **within a page** — page membership is decided before
  any availability is computed, so a supplier on page 2 can outscore every
  supplier on page 1. See the full breakdown, including the
  `sessionsPerWeek`-week and `daysOfWeek`-denominator details, in
  [Search suppliers by availability](https://docs.gomarketbox.com/guides/search-suppliers-by-availability.md#rank-suppliers-by-fit-availabilitymatch).

## Package slate (a complete N-session plan)

```
POST /v1/projects/{projectId}/availability/package-slate
```

Builds a **slate** — a complete N-session plan for a package, from a single
supplier's availability. Pass a `packageId` (the session count, service and
offering are derived from it) — or, to plan what is left on a credit the
client already owns, its `orderId` and `orderItemId`, optionally with the `clientId` the order must
belong to — plus a location, an IANA `timezone`, a
`lookAheadStartDate` carrying a numeric offset, and an `rrule` with a bounded
`COUNT`. The returned `primarySlate.slateId` books the whole plan in one call
via `POST /v1/projects/{projectId}/orders/{orderId}/package-bookings`.

Two cadence guards apply, each a `400 VALIDATION_ERROR`: `lookAheadStartDate`
must carry a numeric `±HH:MM` offset rather than a `Z` suffix (the slate
builder reads the offset from the last six characters — unlike recurring
search, which now accepts either form), and `rrule` must carry a bounded,
positive `COUNT`. Every session in the returned slate is stamped with
`bookingTz` equal to its **home zone** — the service location's zone, else
the supplier's, else the project default — not the `timezone` you sent.

Responses are `200` when anything is bookable and `422` when nothing is —
specifically, when `primarySlate`, `partial` **and** `cadenceAlternatives`
are all empty.

Planning from a credit uses its remaining sessions (`quantityRemaining`
replaces the `rrule`'s `COUNT`), its own service and offering, and ends at its
`expiresAt`. It works after the package was deleted. Send exactly one source:
neither or both is a `400`. A credit that can't be planned is refused before
any search: `409 ORDER_CANCELLED`, `409 ORDER_ITEM_QUANTITY_UNAVAILABLE` (no
sessions left), `409 PACKAGE_EXPIRED`, `400 NOT_A_PACKAGE_ITEM`,
`400 INVALID_ORDER_REFERENCE`, or `404 NOT_FOUND` for an unknown item. See
[Create a package booking](https://docs.gomarketbox.com/guides/create-a-package-booking.md#book-the-sessions-left-on-a-credit).

> [!NOTE]
>
> **Cadence relaxation.** By default a supplier who can't meet your exact
> `rrule` yields a `422`. Opt in with `cadenceFlexibility` (or
> `guaranteeSlate`) and the response instead carries `cadenceAlternatives`:
> complete N-session plans at a denser, supplier-feasible cadence, each
> directly bookable, under `status: "ALTERNATIVE_CADENCE"` — a **success**,
> returned as `200`. A request that sets neither field sees no change
> whatsoever. Fully documented in
> [Availability and slates](https://docs.gomarketbox.com/guides/availability-and-slates.md).

## Package options (every package of a service)

```
POST /v1/projects/{projectId}/availability/package-options
```

The composite built on `package-slate`: returns every ACTIVE package of a
service, each with its own complete N-session plan and ready-to-book
`slateId`. Cadence defaults to `FREQ=WEEKLY;COUNT={creditCount}`, derived per
package. It accepts the same cadence-relaxation fields.

Unlike `package-slate`, it is **always `200`** — a package that can't be
planned comes back with its own `status` and `reason` rather than failing the
whole request.

## Errors

| Status | When |
| - | - |
| `400` | Missing location, missing `rrule` on a recurring request, recurring `rrule` without `COUNT`, a `timezone` that is not an IANA identifier, a `lookAheadStartDate` that does not parse, a package `lookAheadStartDate` using `Z`, or `time-slots` without `suppliers`. |
| `403` | Missing or unrecognised API key — rejected at the edge, before any scope check — or a key that cannot access this project, or one without Standard API access (`CAPABILITY_NOT_GRANTED`). |
| `404` | `/search` and `/suppliers` — no offering for this `serviceId`/`offeringId`, or no location for this `locationId` (sent without `lat`/`lng`); the message names the id. `package-options` — the service doesn't exist in this project. `package-slate` — the package, or the credit's order item, doesn't exist. |
| `409` | `package-slate` only — the credit can't be planned: no sessions left (`ORDER_ITEM_QUANTITY_UNAVAILABLE`), expired (`PACKAGE_EXPIRED`), or on a cancelled order (`ORDER_CANCELLED`). |
| `422` | `package-slate` only — nothing bookable: no `primarySlate`, no `partial`, and no `cadenceAlternatives`. The `code` is `NO_COMPLETE_SLATE` or `NO_AVAILABILITY`. |

`/search`, `/suppliers` and `/time-slots` report engine failures differently:
inside a `200`, as strings in the body's `errors[]`. An empty result with a
non-empty `errors` is a broken search, not an empty calendar.

See [Errors](https://docs.gomarketbox.com/concepts/errors.md) for the full error envelope.

## Endpoint index

* `POST /v1/projects/{projectId}/availability/search`
* `POST /v1/projects/{projectId}/availability/time-slots`
* `POST /v1/projects/{projectId}/availability/suppliers`
* `POST /v1/projects/{projectId}/availability/package-slate`
* `POST /v1/projects/{projectId}/availability/package-options`


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