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

# Changelog

> New features, updates, and fixes to the MarketBox API.

**November 18, 2026**

## These docs now describe the production API

The docs, the API reference and its "try it" console now name the production API instead of a development host. Nothing in the API's behaviour changed.

**Changed**

* **Base URL.** Every page reads `MARKETBOX_API_URL`, and its value is now the production host. See [Make your first call](https://docs.gomarketbox.com/quickstart.md#2-make-your-first-call). Dashboard links go to the production dashboard.
* **Keys belong to one environment.** A key minted against the development host isn't recognised by the production API. Mint a key in the production dashboard: see [Get a project and an API key](https://docs.gomarketbox.com/quickstart.md#1-get-a-project-and-an-api-key).
* **The "try it" console sends real requests to production.** A booking you create there is a real booking.

**Added**

* **Quickstart** — signing up, creating a project, where the API key and the project ID are, what a first booking needs, and TypeScript for the order and the booking. The booking example no longer uses a fixed date.
* **[Test keys and sandbox](https://docs.gomarketbox.com/concepts/authentication.md#test-keys-and-sandbox)** — there is one kind of key, and no sandbox.

**Fixed**

* **Key prefixes.** Examples showed keys starting `mb_live_` and `mb_test_`. Keys have no prefix.
* **Testing payments.** [Accept payments with Stripe](https://docs.gomarketbox.com/guides/accept-payments-with-stripe.md#test-it) said to use Stripe test mode. Production charges in live mode, and test cards are declined.

**November 17, 2026 (reference corrections)**

## API reference corrections for the November 17 release

The API reference now lists every error and field from the November 17 release. Nothing in the API's behaviour changed, so you don't need to change any requests.

**Fixed**

* **`POST …/orders/{orderId}/payment-intent`** lists `409 PAYMENT_IN_FLIGHT`. The reference also said a reused intent keeps its original amount. It doesn't: an open intent is reused only while it is for the amount owed now. When the amount owed changes, the old intent is canceled and a new one is created. Always use the `clientSecret` from the latest call. See [Accept payments with Stripe](https://docs.gomarketbox.com/guides/accept-payments-with-stripe.md).
* **`POST …/orders/{orderId}/transactions`** lists `422 ORDER_NOT_PAYABLE`: a `SUCCEEDED` `PAYMENT`, or a `COMP` adjustment, on a `CANCELLED` order.
* **`disputeId` and `disputeStatus`** on transactions are described, including what each `disputeStatus` value means.
* **`NOT_SELLABLE` on bookings, hold conversion and package bookings** — the reference said a service that isn't `LIVE` is refused. On these routes only an offering that isn't `ACTIVE` is refused, because they book an order item already bought. Both package-bookings routes now list the code.
* **`START_END_LOCATIONS_DISABLED` and `SETTING_NOT_DELEGATED`** are in the list of error codes.

**November 17, 2026**

## Stricter booking and order rules, traffic-aware offered times, a buffer before each service, and schedule start and end locations

This release makes the open API enforce the booking, order and payment rules the dashboard already applied. Offered times now account for split shifts, traffic and the drive to neighbouring bookings. Services gain an optional buffer before they start. Supplier schedules can name where the day starts and ends, once a project turns that on.

**Several requests that used to succeed are now refused with a 4xx code.** No field was removed or renamed, and every new field is optional or nullable. Regenerate decoders for services, transactions, supplier alerts and supplier-plane schedules. Branch on the new codes rather than retrying them.

**Breaking**

* **A service that isn't `LIVE`, or an offering that isn't `ACTIVE`, is no longer sold.** `POST …/orders` and `POST …/orders/{orderId}/items` answer `422 NOT_SELLABLE`, for example "Service srv\_… is DRAFT and is not sold; only LIVE services take new bookings and orders". A service that wasn't `LIVE` used to be accepted. An inactive offering on an order item used to be `400`. Bookings, hold conversion and package sessions against an order item already bought stay bookable after the service stops being `LIVE`, but answer `422 NOT_SELLABLE` once the offering isn't `ACTIVE`.
* **A `PACKAGE` line for a `DRAFT` or `ARCHIVED` package** on `POST …/orders` is `422 PACKAGE_NOT_ACTIVE`.
* **Your key can't cancel a booking that has taken place.** `POST …/bookings/{bookingId}/status` with `CANCELLED` on an `AWAITING_CONFIRMATION` booking is `400`. Settle it instead, with `COMPLETED` or a no-show.
* **`DELETE …/bookings/{bookingId}` is a cancel first.** A booking your key can't cancel (`AWAITING_CONFIRMATION`, `COMPLETED`, a no-show) is `422 BOOKING_NOT_DELETABLE`, and nothing changes. Deleting a booking that is already cancelled sends no second cancellation email.
* **Moving a settled booking is refused.** A `PATCH …/bookings/{bookingId}` that changes the time or supplier of a booking that isn't `SCHEDULED` or `STARTED` is `422 BOOKING_NOT_AMENDABLE`. Its other fields can still be edited.
* **An attendance report filed with your key now settles the booking.** A `SUPPLIER` report on `POST …/bookings/{bookingId}/reports` moves the booking as the supplier's own report does: attended → `COMPLETED` (or `DISPUTED` when the client reported not attending), did not attend → `SUPPLIER_NO_SHOW`. A `CLIENT` "did not attend" on a completed booking inside the dispute window opens a dispute. A report before the session ends, on a cancelled booking, or a `SUPPLIER` report on a settled booking is `422 BOOKING_NOT_REPORTABLE`. It was `422 UNPROCESSABLE_ENTITY`, and a report never changed the status.
* **Participants only join an open booking.** Registering a participant on a booking that isn't `SCHEDULED` or `STARTED`, or checking one in on a booking that is settled, disputed or cancelled, is `422 BOOKING_NOT_OPEN_FOR_PARTICIPANTS`. An `AWAITING_CONFIRMATION` booking still takes a check-in.
* **A cancelled order takes no new money.** A `PAYMENT` or `COMP` recorded on a `CANCELLED` order is `422 ORDER_NOT_PAYABLE`, "Order ord\_… is CANCELLED and cannot take a payment". A `REFUND` is still recorded.
* **One card payment at a time.** `POST …/orders/{orderId}/payment-intent` while a card payment on the order is in progress is `409 PAYMENT_IN_FLIGHT`.
* **The status routes check the id.** `POST …/offerings/{offeringId}/status` with an unknown or deleted offering is `404 NOT_FOUND`, "Offering not found". It used to write a stub. `POST …/business-models/{businessModelId}/status` with an unknown id is `404`, "Business model not found".

**New**

* **`bufferBeforeStartMinutes` on services** — 0 to 120, default 0, on service responses and on `POST …/services` and `PUT …/services/{serviceId}`. Suggested times leave that gap before a job of the service, online jobs included. It is never busy time, never part of `travelTimeMins`, and never refuses a booking made at a specific time.
* **Start and end locations on supplier-plane schedules** — `startLocation`, `endLocation`, `driveTiming`, `maxTravelOnStartDrive` and `maxTravelOnEndDrive` on `…/suppliers/me/schedules`. All are nullable, and `null` uses the project's default. A write is `422 START_END_LOCATIONS_DISABLED` while the project has the feature off, and `422 SETTING_NOT_DELEGATED` for a setting the project keeps. Sending `null` or the stored value is never refused. The feature is off for every project until it is turned on.
* **`disputeId` and `disputeStatus` on transactions** — set when a card payment is disputed. Read-only.
* **`PAYMENT_NEEDS_REVIEW` in the alert `kind` enum** — with `payload.paymentReason`. It is a staff alert, so `GET …/suppliers/me/alerts` doesn't return it to a supplier. Typed clients should still accept the value. See [Supplier portal: insights and alerts](https://docs.gomarketbox.com/guides/supplier-portal-insights-and-alerts.md#alerts).

**Changed**

* **Offered times.** Each block of a split shift offers its own first and last time. Open slots leave time to drive to and from neighbouring bookings. Drive times account for traffic at the time of day, so rush-hour times can move later or disappear, and `travelTimeMins` reports the drive with traffic. A supplier whose bookings can't be routed shows up in `errors[]` instead of failing the whole search.
* **`POST …/availability/time-slots`** — `metrics.totalTravelTimeRequestsMade` counts distinct drives across the whole request. A recurring window in a time zone ahead of UTC lands on the right weekdays.
* **`POST …/orders/{orderId}/payment-intent` bills `total − amountPaid − amountComped`.** An order paid or comped in full is `400`.
* **A delivered package session cancelled without a `creditTreatment` is `FORFEIT`.** A session still to come is still `RETURN`.
* **`POST …/holds/{reservationId}/release` can answer `409 OCCUPANCY_CONTENTION`.** The hold is still `HELD`. Retry the release.
* **Supplier photo and `active` writes can answer `409 CONFLICT`** when another request changed the same record meanwhile. Read the supplier again and retry.
* **`POST …/clients/me` makes an existing member a client.** An admin or supplier who signs in on your booking site gains the `CLIENT` role.
* **Deleting a supplier-plane schedule keeps a travel zone another schedule uses.**
* **`GET …/orders` with `paymentMethod` keeps settled orders that were later cancelled,** with their `status`.

**What this means for you**

* **Handle the new codes without retrying.** `NOT_SELLABLE`, `PACKAGE_NOT_ACTIVE`, `BOOKING_NOT_DELETABLE`, `BOOKING_NOT_AMENDABLE`, `BOOKING_NOT_REPORTABLE`, `BOOKING_NOT_OPEN_FOR_PARTICIPANTS` and `ORDER_NOT_PAYABLE` won't succeed on retry.
* **Settle sessions that took place instead of cancelling them.**
* **Expect offered times to change** at rush hour and around split shifts. Don't cache drive times across times of day.
* **Accept the new optional fields** on services, transactions, alerts and schedules.

Full detail: [Errors → Common error codes](https://docs.gomarketbox.com/concepts/errors.md#common-error-codes), [Bookings](https://docs.gomarketbox.com/resources/bookings.md), [Cancel or reschedule a booking](https://docs.gomarketbox.com/guides/cancel-or-reschedule-a-booking.md), [Orders](https://docs.gomarketbox.com/resources/orders.md), [Services](https://docs.gomarketbox.com/resources/services.md), [Availability](https://docs.gomarketbox.com/resources/availability.md), [Supplier portal: availability](https://docs.gomarketbox.com/guides/supplier-portal-availability.md).

**November 5, 2026**

## Supplier access checks and refusal codes, expired slates can't be held, client disputes, and 4xx instead of 500s

This release lets a supplier portal check, on sign-in, whether the person may use the supplier plane. Supplier-plane refusals now name their cause. Holds refuse slates that have expired. A client's "didn't attend" can open a dispute. Deleting an order that holds bookings or money is refused. Many caller mistakes that came back as `500 INTERNAL_ERROR` now return a 4xx that says what to fix.

**Two breaking changes: `SUGGESTION_EXPIRED` on holds, and the supplier-plane refusal codes.** Separately, `VERSION_CONFLICT` replaces `CONFLICT` for a stale availability version, so that is a code change too if you match on `code`. No field was removed or renamed. Regenerate decoders for `GET /suppliers/{supplierId}`, which gains a required `access` object.

**Breaking**

* **`SUGGESTION_EXPIRED`: a hold from an expired slate is refused.** `POST …/holds` with `slateId` or `slotIds` past its `resolvableUntil` (24 hours after it was planned) answers `409 SUGGESTION_EXPIRED`, "Slot … is past its resolvable window". Extending a hold the same way is refused too. It used to succeed, holding times planned from availability that may have changed. Plan a fresh slate and hold that. A heartbeat that re-posts the held `intervals` is unaffected. Convert doesn't re-check the window, so a client who takes a while to pay still books. See [Holds](https://docs.gomarketbox.com/resources/holds.md).
* **Supplier-plane refusal codes (statuses unchanged).** `/suppliers/me` routes now name why they refuse, where they used to answer `403 FORBIDDEN` or `404 NOT_FOUND`:

  * `403 NOT_A_MEMBER`, "You are not a member of this project.": no membership of the project. It was `FORBIDDEN`, "No active membership on this project".
  * `403 MEMBERSHIP_INACTIVE`, "Your access to this project has ended.": every role was removed. It was `FORBIDDEN`, "No active membership on this project".
  * `403 NO_SUPPLIER_ROLE`, "You don't have supplier access on this project.": the roles the person acts under lack the route's permission. It was `FORBIDDEN`, "Insufficient permissions for this action".
  * `404 NO_SUPPLIER_ROLE`: the permission passed, but the person acts under no `SUPPLIER` role. It was `NOT_FOUND`, "No supplier record for current user".
  * `404 SUPPLIER_NOT_LINKED`, "Your sign-in isn't linked to a supplier record on this project.": the person holds `SUPPLIER`, but no single supplier record is linked. It was `NOT_FOUND`, "No supplier record for current user".

  A booking, schedule or other id that isn't the supplier's is still `404 NOT_FOUND`. "User account not found. Complete registration first." is still `403 FORBIDDEN`. The client plane (`/clients/me`) is unchanged. See [Supplier portal → Refusals](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md#refusals).

**Added**

* **`GET /v1/projects/{projectId}/suppliers/me/access`** — takes the API key and the person's access token, and always answers `200` with `{ allowed, reasonCode, message, supplierId, roles, membershipStatus }`. `reasonCode` is one of seven codes:

  * `SUPPLIER_ACTIVE`, the only one with `allowed: true`;
  * `SUPPLIER_RECORD_INACTIVE`, `NO_ACCOUNT`, `NOT_A_MEMBER`, `MEMBERSHIP_INACTIVE`, `NO_SUPPLIER_ROLE` and `SUPPLIER_NOT_LINKED`.

  It ignores `X-MB-Acting-Role`. Wrong credentials still fail with `401` or `403`. See [Check access first](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md#check-access-first).
* **`access` on `GET /v1/projects/{projectId}/suppliers/{supplierId}`** — `userId`, `invitationStatus`, `roles` (empty unless the membership is `ACTIVE`), `membershipStatus` (`ACTIVE`, `INACTIVE` or `null`) and `accessEndedAt`. `accessEndedAt` is set when the person is unlinked, and is `null` for removals made before this release. `GET /suppliers` and `POST /availability/suppliers` don't carry it. See [Removed, or never a supplier](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md#removed-or-never-a-supplier).
* **`conflicts[].supplierId`** on `409 SLOT_HELD` / `SLOT_BOOKED`: the supplier whose calendar is blocked, `null` when unknown. It was in the schema but never sent.

**Changed**

* **A stale availability `version` is `409 VERSION_CONFLICT`, not `409 CONFLICT`.** This covers `PATCH` on `…/suppliers/me/schedules/{scheduleId}`, `…/blocked-times/{blockedTimeId}` and `…/travel-zones/{travelZoneId}`. It also covers another write landing during a `DELETE` of any of them. The status is still `409`. An overlapping `ACTIVE` schedule stays `409 CONFLICT`, so branch on `code`. See [Supplier portal → Set working hours](https://docs.gomarketbox.com/guides/supplier-portal-availability.md#set-working-hours).
* **Acting as `CLIENT` never serves a supplier's bookings.** A request to the supplier plane's bookings routes with `X-MB-Acting-Role: CLIENT` is `404 NO_SUPPLIER_ROLE`, even when the person has a linked supplier record. It used to answer `200`. The alerts routes always read the supplier's own inbox, whatever the header names.
* **`DELETE …/orders/{orderId}` refuses a real order.** An order holding a booking (booked or delivered), or a `PENDING` or `SUCCEEDED` payment or refund, answers `409 ORDER_NOT_DELETABLE`, and nothing changes. Cancel it with `POST …/orders/{orderId}/status` instead. An order that books nothing and took no money still deletes. See [Orders](https://docs.gomarketbox.com/resources/orders.md#the-order-lifecycle).
* **A client's "didn't attend" can open a dispute.** A supplier report of `attended: true` makes the booking `DISPUTED`, not `COMPLETED`, when a client report already says `attended: false`. A client's `attended: false` within 24 hours of a booking becoming `COMPLETED` also makes it `DISPUTED`, whoever completed it. Client reports filed with your key count toward the first case only. Nothing settles a booking on a timer. See [Attendance and disputes](https://docs.gomarketbox.com/resources/bookings.md#attendance-and-disputes).

**Fixed**

* **Booking writes return 4xx instead of 500.** `POST …/bookings`, `PATCH …/bookings/{bookingId}`, `POST …/holds/{reservationId}/convert` and both package-bookings routes now answer:
  * `409 SLOT_HELD` / `SLOT_BOOKED` when a reschedule's new time is taken, with `conflicts[]` and `hint`;
  * `409 OCCUPANCY_CONTENTION` when the supplier's calendar is under heavy writes;
  * `409 VERSION_CONFLICT` when the booking changed since you read it;
  * `404 NOT_FOUND` for an unknown location, and `400 BAD_REQUEST` for one of the wrong type or another supplier's travel zone;
  * `422 UNPROCESSABLE_ENTITY` for a `PHYSICAL` Location without coordinates.
* **Converting a `PHYSICAL` hold works.** It used to fail with a `500`.
* **Converting a package hold answers package refusals with their own codes,** as `POST …/package-bookings` does, instead of `500`: `409 ORDER_ITEM_QUANTITY_UNAVAILABLE`, `409 PACKAGE_EXPIRED`, `422 PACKAGE_SLATE_TOO_LARGE_FOR_ATOMIC` and `422 BEST_EFFORT_NOT_ENABLED`. Nothing is booked in any of them.
* **An offering's `holdDurationMinsOverride` is saved.** It was accepted but dropped, so holds ignored it. A hold placed from a slate or slot of that offering now lasts that long when the request sends no `holdDurationMins`. `null` clears it.
* **`NOT_A_PACKAGE_SERVICE` is listed with the other error codes.** The API already returned it (`400`) for a `PACKAGE` booking or convert whose service has no active `PACKAGE` business model.
* **`POST …/orders/{orderId}/items` with `skuType: "PACKAGE"`** is `400 VALIDATION_ERROR`: "skuType: a PACKAGE line can only be added when the order is created: send it in POST /orders items\[] with a packageId". Nothing is written. The request schema no longer lists `PACKAGE` for this route.
* **`POST …/availability/search` and `POST …/availability/suppliers` with an unknown id** are `404 NOT_FOUND`, naming it. For an offering, the message is "Service offering off\_… not found on service srv\_…". For a `locationId` sent without `lat`/`lng`, it is "Location loc\_… not found". A search location with no coordinates is `400 BAD_REQUEST`, "Could not resolve coordinates for the requested location".
* **Updating an offering or a business model with an unknown id is `404 NOT_FOUND`.** `PUT …/offerings/{offeringId}` ("Offering not found") and `PUT …/business-models/{businessModelId}` ("Business model not found") used to write a new, partial record. Nothing is written now. The status routes are unchanged.
* **A supplier's move under calendar contention** (`PATCH …/suppliers/me/bookings/{bookingId}`) is `409 OCCUPANCY_CONTENTION`, not `500`.
* **An offering with no `DEFAULT` price rule** is `422 OFFERING_NOT_PRICED` on every write that prices it, not `500`.
* **`PATCH …/suppliers/me` refuses unknown `serviceIds` and `skillIds`** with `400 BAD_REQUEST` naming them, before anything is written. It used to save them.
* **Deleting an order cancels its bookings.** A delete sets the order `CANCELLED`, but its bookings used to stay `SCHEDULED`. Now any booking that reaches the order during the delete is cancelled, without emails.
* **Package-booking examples use the real `off_` offering prefix.** The reference showed `offr_`.

**What this means for you**

* **Hold only fresh slates.** On `409 SUGGESTION_EXPIRED` from `POST …/holds`, plan a new slate rather than retrying.
* **Match the new supplier-plane codes.** If your portal branches on `FORBIDDEN` or `NOT_FOUND` from `/suppliers/me` to detect lost access, also branch on `NOT_A_MEMBER`, `MEMBERSHIP_INACTIVE`, `NO_SUPPLIER_ROLE` and `SUPPLIER_NOT_LINKED`.
* **Check supplier access on sign-in.** Call `GET /suppliers/me/access` when the person signs in and when your portal renews its session. Use the plane only when `allowed` is `true`; otherwise show `message`. Don't send `X-MB-Acting-Role` from a portal.
* **Tell removed from never invited with `accessEndedAt`.** If your app reads supplier data with the API key, end a supplier's session when the record has no link and `accessEndedAt` is set.
* **Branch on `VERSION_CONFLICT` in your supplier portal.** On it, re-read the row and retry. Show an overlap message only on `CONFLICT`.
* **Cancel orders instead of deleting them.** Keep delete for an order raised in error that books nothing and took no money.
* **Don't treat `COMPLETED` as final for 24 hours.** Anything you do once a session is delivered, such as payouts or follow-ups, should wait out the dispute window.
* **Handle `DISPUTED` wherever you show a booking's status.** An operator resolves it in the MarketBox console; your key can't.
* **Stop retrying writes that failed with a 500.** The same failures now arrive as a 4xx that says what to fix. Don't retry those either: fix the id or the request.

Full detail: [Supplier portal: sign-in and access](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md), [Holds](https://docs.gomarketbox.com/resources/holds.md), [Orders → The order lifecycle](https://docs.gomarketbox.com/resources/orders.md#the-order-lifecycle), [Bookings → Attendance and disputes](https://docs.gomarketbox.com/resources/bookings.md#attendance-and-disputes), [Bookings → Creating a booking](https://docs.gomarketbox.com/resources/bookings.md#creating-a-booking), [Supplier portal → Set working hours](https://docs.gomarketbox.com/guides/supplier-portal-availability.md#set-working-hours), [Suppliers → Who can sign in as this supplier](https://docs.gomarketbox.com/resources/suppliers.md#who-can-sign-in-as-this-supplier), [Order lifecycle after checkout](https://docs.gomarketbox.com/guides/order-lifecycle-after-checkout.md), [Search suppliers by availability](https://docs.gomarketbox.com/guides/search-suppliers-by-availability.md), [Errors](https://docs.gomarketbox.com/concepts/errors.md#common-error-codes).

**October 26, 2026**

## Package credits: plan from a credit, clients book their own, and cancelled orders book nothing; supplier alerts

You can now plan a slate from a credit the client already owns, and the signed-in client can book their own credit through a new client-plane route. A package credit books only its own offering, and a cancelled order's credits can no longer be planned or booked. Your supplier portal can now show the dashboard's alerts, and supplier emails can link to your portal.

**Two breaking changes, two behaviour changes, the rest additive.** No field was removed or renamed. Strict response decoders need a regeneration for `quantityReturned` on `GET …/clients/me/credits`, and for the `409` bodies of `POST …/bookings` and `POST …/holds/{reservationId}/convert`, which the spec now describes as a union with the plain error envelope.

**Breaking**

* **A package credit books only its own service and offering.** `POST …/orders/{orderId}/package-bookings` used to accept sessions of any offering. Every service line of every session must now match the order item's `serviceId` and `offeringId`, or the call is `400 ORDER_ITEM_SERVICE_MISMATCH` and nothing is booked. This applies to `slateId`, `slotIds` and `sessions`.
* **A `CANCELLED` order plans and books nothing.** `POST …/availability/package-slate` (from a credit), `POST …/orders/{orderId}/package-bookings`, `POST …/bookings` and `POST …/holds/{reservationId}/convert` answer `409 ORDER_CANCELLED` for an order that is `CANCELLED`. Convert refuses even a hold that already converted. `DRAFT`, `PENDING` and `PAID` orders book as before: payment is still not a gate.

**Changed**

* **A same-key retry replays after the credits ran out.** Retrying `POST …/package-bookings` with the same `idempotencyKey` and body now returns the stored `201`, even when the first call used the last credits. It used to be `400 ORDER_ITEM_QUANTITY_UNAVAILABLE`. A replay sends no second confirmation email. A `slateId` or `slotIds` retry must still arrive within the slate's window.
* **A reused key with a different body is always `409 IDEMPOTENCY_KEY_CONFLICT`,** even when that body is invalid on its own. It used to get that body's `400` or `404`.
* **Stale-slate `freshSuggestions` are planned from the order item you are booking** — its remaining sessions, offering and expiry — so they can be booked on it. `null` when the item has nothing left to plan.
* **`DELETE …/suppliers/{supplierId}` can answer `409 CONFLICT`** when the supplier's sign-in changes during the delete. Try again.

**New**

* **Plan a slate from a credit.** `POST …/availability/package-slate` takes `orderId` + `orderItemId` instead of `packageId`. It plans the credit's remaining sessions in its own offering, ends at its `expiresAt`, and works after the package was deleted. Send exactly one source. Add an optional `clientId` to have the order checked against that client: another client's order is refused like a missing one (`400 INVALID_ORDER_REFERENCE`). A credit that can't be planned is `409 ORDER_ITEM_QUANTITY_UNAVAILABLE`, `409 PACKAGE_EXPIRED`, `409 ORDER_CANCELLED`, `400 NOT_A_PACKAGE_ITEM`, `400 INVALID_ORDER_REFERENCE` or `404 NOT_FOUND`.
* **`POST …/clients/me/orders/{orderId}/package-bookings`** — the signed-in client books their own credit, with the API key and their access token. Same body, response and refusals as the API-key route. Another client's order is a `404` identical to a missing one. A credit `GET …/clients/me/credits` would not list is `409 CREDIT_NOT_BOOKABLE`. Booking by `slateId` or `slotIds` needs a slate planned from that credit.
* **`quantityReturned` on `GET …/clients/me/credits`** — the sessions cancellations have returned to the credit, ever. Already counted in `quantityRemaining`; a returned session may have been booked again since.
* **Supplier alerts on the supplier plane.** `GET …/suppliers/me/alerts`, `GET …/suppliers/me/alerts/summary`, `POST …/suppliers/me/alerts/read-all` and `POST …/suppliers/me/alerts/{alertId}/read` — the dashboard's bell, from the same inbox. A cursor from another `filter` is `400 INVALID_CURSOR`.
* **Supplier emails can link to your portal.** When a project admin sets a supplier portal URL in the dashboard, the supplier booking emails link there, with `bookingId` when the email is about one booking.

**What this means for you**

* **Plan package slates for the offering the credit was sold with.** Plan from the credit itself to be sure. Handle `400 ORDER_ITEM_SERVICE_MISMATCH`.
* **Handle `409 ORDER_CANCELLED` as final.** Don't retry; offer a new order.
* **Keep the same `idempotencyKey` when you retry a booking,** and a fresh one for each new attempt.
* **Don't add `quantityReturned` to `quantityRemaining`.** It is already included.

Full detail: [Create a package booking → What a booking call checks](https://docs.gomarketbox.com/guides/create-a-package-booking.md#what-a-booking-call-checks), [Create a package booking → Book the sessions left on a credit](https://docs.gomarketbox.com/guides/create-a-package-booking.md#book-the-sessions-left-on-a-credit), [Book a client's package credit → What the booking call checks](https://docs.gomarketbox.com/guides/book-a-package-credit.md#what-the-booking-call-checks), [Supplier portal → Alerts](https://docs.gomarketbox.com/guides/supplier-portal-insights-and-alerts.md#alerts), [Supplier portal → Links in MarketBox emails](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md#links-in-marketbox-emails), [Errors → Package credit codes](https://docs.gomarketbox.com/concepts/errors.md#package-credit-codes).

**October 21, 2026**

## The supplier plane, site events, and API-key capabilities

Suppliers can now manage their own work from your branded portal. The new **supplier plane**, `/v1/projects/{projectId}/suppliers/me`, carries their profile and photo, bookings and attendance reports, cancel and reschedule, working hours, blocked time, travel zones, venues, and demand and search insights. Your site can also report which suppliers it showed, so suppliers' search insights count them. API keys now carry **capabilities**, and a key without standard access is refused.

**One breaking change, two behaviour changes, the rest additive.** No field was removed or renamed. The breaking change cuts off no live key today. Strict response decoders need a regeneration for `searchId`, `position`, `engineEnabled`, `attribution` and `participantSettings`.

**Breaking**

* **A key without Standard API access is refused.** Every route except `POST …/events` now needs the `*` capability. A key with no capabilities ticked, or only **Site events**, gets `403 CAPABILITY_NOT_GRANTED` before anything else is read. Keys minted before capabilities existed are treated as `*` and keep working.

**Changed**

* **End-user routes require an `ACTIVE` membership.** Every `/clients/me` route except onboarding, and every `/suppliers/me` route, checks the person's membership of the project on each request. No membership is `403 FORBIDDEN`, "No active membership on this project". When the business removes a person's role, their next call is refused.
* **Onboarding refuses a removed client.** `POST …/clients/me` answers `403 MEMBERSHIP_INACTIVE` for a person whose access the business removed, and reads or links nothing.
* **Coming: end-user tokens must come from your Application's own client.** A token issued to another client — the MarketBox dashboard's or another Application's — is logged today and still accepted. Once enforcement is switched on, it is `401 UNAUTHORIZED`.

**New**

* **The supplier plane** — 33 operations under `/v1/projects/{projectId}/suppliers/me`, each the twin of a dashboard screen. They take the API key and the supplier's access token. Cancel and reschedule follow the service's participant settings, with new codes `PARTICIPANT_ACTION_DISABLED`, `BOOKING_NOT_SCHEDULED`, `NOTICE_WINDOW_PASSED`, `NEW_START_INSIDE_NOTICE_WINDOW`, `SLOT_UNAVAILABLE` and `SLOT_UNVERIFIABLE`. Attendance reports add `BOOKING_ALREADY_SETTLED` and `BOOKING_NOT_REPORTABLE`. The profile adds `FIELD_NOT_SELF_EDITABLE`; insights add `INSIGHTS_DISABLED`.
* **`GET …/locations` and `GET …/locations/{locationId}`** — the project's venues, virtual locations and travel-zone areas, with the API key alone. Not paginated. The single read returns inactive locations too.
* **`GET …/skills`** — the project's skills, for a supplier profile's skill picker and the `skills` availability filter.
* **Site events.** `POST …/events` (from your server, needs the `events:write` capability) and `POST …/events/beacon` (from the browser, with a publishable key and an origin allowlist). New codes `PAYLOAD_TOO_LARGE` (413), `RATE_LIMITED` (429) and `SERVICE_UNAVAILABLE` (503).
* **`searchId` and `position` on every search.** `POST …/availability/search`, `/suppliers`, `/package-slate`, `/package-options`, `/time-slots` and `GET …/suppliers` return a `searchId` (also the `X-MB-Search-Id` header), and rank each supplier or slate with a 0-based `position`. `POST …/availability/search` also returns `suppliers`. Two optional request headers, `X-MB-Session-Key` and `X-MB-Client-Kind`, tag a search for insights.
* **`engineEnabled` on `POST …/availability/search`.** `false` means the project's scheduling engine is off, so `timeSlots` is empty because it wasn't computed.
* **`attribution` on `POST …/orders`** — the `searchId`, `sessionKey` and `surface` the purchase came from. Copied onto every booking the order funds.
* **`participantSettings` on services** — what suppliers and clients may do with, and see on, bookings of the service. Replaced whole on `PUT`.
* **`X-MB-Acting-Role` is checked.** An end-user request naming a role the person doesn't hold is `403 ACTING_ROLE_NOT_HELD`.

**What this means for you**

* **Check every Application has Standard API access.** Open **API Access** in the dashboard. A key with nothing ticked, or only **Site events**, now gets `403 CAPABILITY_NOT_GRANTED`.
* **Forward the access token from your own Application's client** on every `/clients/me` and `/suppliers/me` call. Don't forward the ID token, or a dashboard token.
* **Handle `403` on end-user routes as "access removed".** Show the person how to contact the business, not a retry.
* **Report what you draw.** Send `search.rendered` with each search's `searchId`. A search you don't report counts for nothing in suppliers' insights.
* **Check `engineEnabled`** before telling a client nobody is free.

Full detail: [Build a supplier portal](https://docs.gomarketbox.com/guides/build-a-supplier-portal.md), [Report site events](https://docs.gomarketbox.com/guides/report-site-events.md), [Locations and skills](https://docs.gomarketbox.com/resources/locations.md), [Authentication → Capabilities](https://docs.gomarketbox.com/concepts/authentication.md#capabilities), [End-user authentication → Who may call an end-user route](https://docs.gomarketbox.com/concepts/end-user-authentication.md#who-may-call-an-end-user-route), [Availability → Search](https://docs.gomarketbox.com/resources/availability.md#search-who-is-available), [Orders → Attribution](https://docs.gomarketbox.com/resources/orders.md#attribution), [The booking engine model → Participant settings](https://docs.gomarketbox.com/concepts/booking-engine-model.md#participant-settings), [Errors](https://docs.gomarketbox.com/concepts/errors.md).

**September 24, 2026**

## Package purchases are taxed, and order tax is computed, not set

The platform now computes every order's tax, and package lines are taxed like any other line. A line with no tax says why. `PATCH …/orders/{orderId}` no longer lets you overwrite tax.

**One breaking change, the rest a behaviour change and additive fields.** No field was removed or renamed. Strict response decoders need a regeneration for `taxExemptReason` on order items.

**Breaking**

* **`tax` on `PATCH …/orders/{orderId}` can no longer change the order.** It is accepted only when it equals both the tax the lines compute and the tax the order stores. Any other figure is `400 TAX_MISMATCH`, and nothing is written. The same code is returned when the order has lines in a different currency. Omit `tax`.

**Changed**

* **Package lines are taxed.** A `PACKAGE` line now takes the tax its price rule resolves, like a single-session line. Package lines written between June and September 2026 keep their zero tax.
* **The service's tax settings are the last fallback.** When neither the matched price rule nor its parent rules set tax, a line uses the service's `taxSettings`. Lines that used to carry no tax can now be taxed.
* **A taxable fee borrows the rate of the first line taxed at a positive rate.** Untaxed and 0% lines no longer shadow a taxed line listed after them, so line order no longer changes a fee's tax.

**New**

* **`taxExemptReason` on order items** — why a line carries no tax: `NO_RATE`, `NOT_TAXABLE`, `ZERO_RATE`, `MIGRATED_V1` or `PACKAGE_EXEMPT_LEGACY`. Absent when the line is taxed at a positive rate, and on lines written before the field existed.

**What this means for you**

* **Stop sending `tax` on `PATCH …/orders/{orderId}`.** Handle `400 TAX_MISMATCH` if you can't remove it yet.
* **Show the tax the API returns on package checkouts.** Package totals now include tax where the price rule or service sets a rate.
* **Branch on `taxExemptReason`, not on `skuType`,** to explain a zero tax.

Full detail: [Orders → How tax is computed](https://docs.gomarketbox.com/resources/orders.md#how-tax-is-computed), [Orders → Updating an order](https://docs.gomarketbox.com/resources/orders.md#updating-an-order), [Service fees → A taxable fee borrows the rate of a taxed line](https://docs.gomarketbox.com/concepts/service-fees.md#a-taxable-fee-borrows-the-rate-of-a-taxed-line), [Errors](https://docs.gomarketbox.com/concepts/errors.md).

**September 23, 2026**

## Orders settle from the ledger, cancels settle the credit, and clients carry their real names

This release makes money and credit follow one rule. An order becomes `PAID` only when its ledger covers its total. Cancelling a package session returns or forfeits its credit in the same write. Onboarding also accepts the name your checkout collected, so a client who signed up with an email address is no longer shown under the part before the `@`.

**Three breaking changes, the rest additive.** No field was removed or renamed. See **Breaking** below. Strict response decoders need a regeneration for the new booking, order, order-item, transaction and client-address fields.

**Breaking**

* **`PAID` can no longer be requested.** `POST …/orders/{orderId}/status` answers a `PAID` target with `409 ORDER_NOT_SETTLED`. An order becomes `PAID` when its ledger covers its total: record cash, external or comp money with `POST …/orders/{orderId}/transactions`, and let the Stripe webhook settle cards. A `PAID` request is refused with that `409` from every status, including `PENDING`.
* **`NO_SHOW` can no longer be set.** Sending it to `POST …/bookings/{bookingId}/status` is a `400`. Send `CLIENT_NO_SHOW` or `SUPPLIER_NO_SHOW`. Bookings recorded before the split still carry `NO_SHOW` on every read, and will indefinitely.
* **An order line the service is not sold as is refused.** `POST …/orders` and `POST …/orders/{orderId}/items` return `422 SERVICE_NOT_SOLD_AS` when the service has no active rate of the line's kind, such as a `SINGLE_SESSION` line with no active `SINGLE_BOOKING` rate. Such lines used to be written with no rate attached, and so without its fees.

**New**

* **`firstName` and `lastName` on `POST …/clients/me`**, beside `phone`. Each field you send overwrites the stored value and is copied to the client's record in Stripe. Blank or `null` means not sent. At most 80 characters after trimming.
* **`PATCH …/clients/me`** — change the signed-in client's `firstName`, `lastName` or `phone`. Names can be changed but not cleared; `phone: null` clears the phone. Call it before `POST /orders` so emails use the new name.
* **`creditTreatment` on `POST …/bookings/{bookingId}/status`**, with `CANCELLED` only. `RETURN` (the default for a package session) puts the session back on the order item and records a `CREDIT_REVERSAL`. `FORFEIT` keeps it spent. Sending it for a booking with no package credit is `422 NO_SESSION_CREDIT`, and nothing is cancelled.
* **Three listing modes on `GET …/orders`.** `status` is no longer required. Send `status`, or `paymentMethod` (with `startSettledAt`/`endSettledAt`), or neither to list every order (with `startCreatedAt`/`endCreatedAt`). Mixing modes is a `400`. The no-filter mode is missing orders created before this release until a backfill runs.
* **`reason` and `idempotencyKey` on `POST …/orders/{orderId}/transactions`.** `reason` is required with `source: "COMP"`. The same `idempotencyKey` on the same order returns the first row as `200` with `replayed: true` instead of recording the money twice. A first recording is `201` with `replayed: false`.
* **`skills` on `POST …/availability/search`** — supplier skill ids a supplier must all hold to be considered.
* **`bio: null` on `PUT …/suppliers/{supplierId}`** clears the bio. Omitting it still keeps it.
* **New response fields.**
  * Order: `paymentMethod`, `settledAt`, `amountComped`.
  * Order item: `priceSource` (`RULE` or `MANUAL`).
  * Booking: `creditTreatment`, `cancellationInitiatedBy`, `cancellationReasonCode`, `durationOverrideMinutes`, `durationOverrideReason`.
  * Transaction: `channel`, `reason`, and the `CREDIT_REVERSAL` kind.
  * Client address: `latitude`, `longitude`.

**Changed**

* **Cancelling settles the order item.** A cancelled package session returns its credit by default. A cancelled single session closes its allocation and returns no quantity. `DELETE …/bookings/{bookingId}` settles the same way as a default cancel.
* **The card is saved on public-API checkout.** When the order's client has an email, the PaymentIntent sets `setup_future_usage: off_session`. Tell the client their card will be saved.
* **Body ids are fenced to your project.** A `clientId` or `supplierId` from another project is a `404` with nothing written, on booking create and update, participants, order create, package bookings, holds and manual transactions.
* **A booking line must match its order item's kind.** A `businessModelType` the order item is not sold as is `400 ORDER_ITEM_BUSINESS_MODEL_MISMATCH`.
* **Cancellation emails** report what happened to the client's session credit, and do not include the `cancellationReason` text.

**What this means for you**

* **Stop setting orders to `PAID`.** Record the payment instead, and read `status` back.
* **Send an `idempotencyKey`** on every manual transaction you might retry, and branch on `replayed`.
* **Send `reason` with every comp.**
* **Replace `NO_SHOW` in requests** with `CLIENT_NO_SHOW` or `SUPPLIER_NO_SHOW`. Keep handling it in responses.
* **Decide your late-cancel policy.** Send `creditTreatment: "FORFEIT"` when a package session should stay spent. Otherwise it goes back to the client.
* **Send `firstName` and `lastName` on onboarding**, especially for email-and-password sign-ups.
* **Handle `422 SERVICE_NOT_SOLD_AS`** on order create, and check the rates on services you sell.
* **Don't treat the no-filter orders list as complete** for historical data. List by `status` when you need every order.
* **Tell clients at checkout that their card will be saved.**

Full detail: [Orders → Settling an order](https://docs.gomarketbox.com/resources/orders.md#settling-an-order), [Orders → Listing orders](https://docs.gomarketbox.com/resources/orders.md#listing-orders), [Bookings → Cancelling and the package credit](https://docs.gomarketbox.com/resources/bookings.md#cancelling-and-the-package-credit), [Booking flow auth → Onboard the client](https://docs.gomarketbox.com/guides/booking-flow-auth.md#onboard-the-client), [Errors](https://docs.gomarketbox.com/concepts/errors.md).

**September 10, 2026**

## Every slot time is one instant, every zone is IANA, and bookings say who moved them

Availability slots used to take their clock digits from the supplier's own zone and their offset from the `timezone` you passed, so when the two differed the string described a different moment than the one the supplier was free at — a Toronto supplier viewed with `timezone: "America/Los_Angeles"` was three hours off. Recurring schedules also used one fixed offset for their whole span and drifted an hour after a daylight-saving change. Both are fixed, and the booking lifecycle now carries the statuses the platform has been using internally.

**Additive on the wire, with one breaking validation change.** No field was removed or renamed. A request that previously sent an abbreviated timezone will now be rejected — see **Breaking** below. Strict response decoders need a regeneration for the new booking statuses and the new slot and envelope fields.

**New**

* **`timeSlotStartUtc` on every slot** in `timeSlots[]` and `openSlots[]` from `POST /v1/projects/{projectId}/availability/search` and `…/time-slots`. The slot start in UTC, always `Z`-suffixed, always the same instant as `timeSlotDateAndTime`. Prefer it as the booking anchor. Package slates derive each session's `bookingStartUtc` from it. This is a response shape:

```json theme={null}
{
  "supplierId": "sup_01kv60qgnef2kt3pvqgwmkbzfr",
  "timeSlotDateAndTime": "2026-11-08T09:00:00-05:00",
  "timeSlotStartUtc": "2026-11-08T14:00:00.000Z"
}
```

* **`supplierZones` on `POST /v1/projects/{projectId}/availability/search`** — each returned supplier's own profile zone, keyed by `supplierId`. The recommended `bookingTz` for a virtual booking with no service location: location zone, else supplier zone, else project default. A supplier missing from the map has no profile zone.
* **Four booking statuses**: `AWAITING_CONFIRMATION`, `DISPUTED`, `CLIENT_NO_SHOW`, `SUPPLIER_NO_SHOW` — on every booking response and on the `status` filter of the three list endpoints. `AWAITING_CONFIRMATION` and `DISPUTED` are entered by the platform after a session ends and can only be observed. `CLIENT_NO_SHOW` / `SUPPLIER_NO_SHOW` replace `NO_SHOW`, which no longer said which side was absent. See [Bookings → The booking lifecycle](https://docs.gomarketbox.com/resources/bookings.md#the-booking-lifecycle).
* **`statusUpdatedBy` and `statusUpdatedByCapacity` on every booking** — who last changed the status and in what capacity (`ADMIN`, `SUPPLIER`, `CLIENT`, `SYSTEM`, `API`). A change made through the public API is attributed to the API key that made it, in the `API` capacity.
* **`lookAheadStartDate` accepts a `Z` instant on recurring `…/availability/search`.** A `Z` suffix and a numeric offset are equally valid there; the "must carry a numeric offset" `400` is gone from that endpoint. `…/package-slate` and `…/package-options` still require a numeric offset.

**Changed**

* **Corrected slot times.** `timeSlotDateAndTime` keeps its name and now renders the slot instant in the response `timezone` with that zone's offset **at that instant**, so digits and offset always agree and the string always parses to `timeSlotStartUtc`. If your code parses the whole string you will simply see correct times. If it reads only the clock digits, pass `timezone` explicitly to keep receiving that zone's clock. On `…/availability/suppliers`, `startUtc` is now the engine instant verbatim and `startLocal` is rendered in the response `timezone`.
* **Daylight saving.** A supplier's weekly schedule now keeps its local wall clock across a transition (a 9:00 lesson stays 9:00 in the supplier's zone) and the UTC instant shifts. That is correct; do not "fix" it on your side.
* **Package sessions are stamped with the home zone.** Slots from `…/package-slate` and `…/package-options`, and the bookings created from them, carry `bookingTz` equal to the session's home zone — the service location's zone, else the supplier's, else the project default — instead of the `timezone` you sent. `bookingStartUtc` is unchanged.
* **Recurring search windows resolve on the local date.** On recurring `…/availability/search`, the window and the recurrence anchor are read on the local date in the request `timezone`, so a midnight-UTC `lookAheadStartDate` against a zone west of Greenwich anchors one day earlier than before. A value that does not parse is a `400` in the standard error envelope rather than a raw validation payload.
* **`POST …/bookings/{bookingId}/status` request enum is narrower than the response.** `SCHEDULED` and `DISPUTED` are no longer advertised as settable — they were always rejected. `NO_SHOW` is **deprecated**, still accepted, and will be removed in a later version (it was: since the September 23, 2026 release, sending `NO_SHOW` is a `400`). An API key can request every transition an operator can except resolving a dispute or reversing a settled booking back to `AWAITING_CONFIRMATION`. A transition the booking cannot make is a `400` naming the booking's current status.
* **Supplier `timezone` drives the daily agenda email.** It is used verbatim as the schedule zone for the supplier's 07:00 agenda; unset inherits the project default.

**Breaking: timezone values must be IANA identifiers**

Every zone field is validated on write. Accepted: any IANA identifier containing a `/` (`America/Toronto`, `Australia/Sydney`, `Asia/Kolkata`) and the literal `UTC`; deprecated aliases with a `/` (`US/Pacific`) still pass. **Rejected with `400 VALIDATION_ERROR`:** abbreviations (`EST`, `PST`, `IST`, `CET`), legacy names without a `/` (`Hongkong`, `Japan`), numeric offsets (`-05:00`), and values with surrounding whitespace. The message names the field:

```json theme={null}
{
  "code": "VALIDATION_ERROR",
  "message": "bookingTz: Must be an IANA timezone identifier such as America/Toronto (abbreviations like EST are not accepted)",
  "statusCode": 400,
  "requestId": "e21d9f4a-6b8c-4e3d-a175-2c9f6b0d8a53"
}
```

| Endpoint | Field |
| - | - |
| `POST …/availability/search`, `…/suppliers`, `…/package-slate`, `…/package-options` | `timezone` |
| `POST …/bookings`, `PATCH …/bookings/{bookingId}` | `bookingTz` |
| `POST …/holds` | `intervals[].bookingTz` |
| `POST …/orders/{orderId}/package-bookings` | `bookingTz` |
| `POST …/suppliers`, `PUT …/suppliers/{supplierId}` | `timezone` |

Stored values are not re-validated on read.

**What this means for you**

* **Search your code for hard-coded zone strings** sent to the API and replace abbreviations with IANA ids: `EST` → `America/Toronto` or `America/New_York`, `PST` → `America/Los_Angeles`, `IST` → `Asia/Kolkata`.
* **Prefer `timeSlotStartUtc`** for anything that computes with a slot time; treat `timeSlotDateAndTime` as a display convenience.
* **If you rely on the clock digits** in `timeSlotDateAndTime`, pass `timezone` explicitly on every availability request.
* **If you display package sessions using `bookingTz`**, expect the home zone rather than your request zone.
* **Regenerate response types** for the four new statuses, `statusUpdatedBy`, `statusUpdatedByCapacity`, `timeSlotStartUtc` and `supplierZones`. Handle `AWAITING_CONFIRMATION` and `DISPUTED` as in-flight, not failed.
* **Stop sending `NO_SHOW`.** Send `CLIENT_NO_SHOW` or `SUPPLIER_NO_SHOW` instead.
* **A "no `Z`" guard on `lookAheadStartDate` is now only needed for the package endpoints**, not for recurring search.

Full detail: [Timezones](https://docs.gomarketbox.com/concepts/timezones.md), [Availability → Slot times and zones](https://docs.gomarketbox.com/resources/availability.md#slot-times-and-zones), [Bookings → The booking lifecycle](https://docs.gomarketbox.com/resources/bookings.md#the-booking-lifecycle).

**September 3, 2026**

## Supplier directory: `servedRegions`, point search, one liveness rule — plus booking locale and E.164 phones

You can now see exactly why a supplier does or does not match the region filter, search the directory by coordinate, and record the language a purchase was made in.

**Purely additive on the wire, with one behaviour change.** No field was removed or renamed and every request valid before this release is still valid. `servedRegions` is a **new required field** on every supplier response, so strict response decoders need a regeneration. The liveness change below can make `locations[]` shorter than it was.

**New**

* **`servedRegions` on every supplier response** — the rows of `GET /v1/projects/{projectId}/suppliers`, the detail endpoint, the create, update, services, skills and avatar responses, and `data[].supplier` on `POST /v1/projects/{projectId}/availability/suppliers`. Sorted slug region paths at every hierarchy level — the **same set** the `country`/`state`/`city` filter matches against, so membership is explainable from the record. `[]` when there is no live schedule with a geocodable zone. This is a response shape:

```json theme={null}
{
  "supplierId": "sup_01kv60qgnef2kt3pvqgwmkbzfr",
  "phone": "+14165550142",
  "locations": [
    { "locationId": "stz_01kv60qgnef2kt3pvqgwmkbzfr", "locationType": "TRAVEL_ZONE", "name": "Scarborough" }
  ],
  "servedRegions": ["ca/", "ca/on/", "ca/on/scarborough/", "ca/on/toronto/"],
  "defaultLocale": "fr-CA"
}
```

* **`lat` + `lng` on `GET /v1/projects/{projectId}/suppliers`** — both or neither. Returns suppliers whose **live travel zone contains the point**, tested against the real polygon or radius, AND-combined with `services`/`skills`. Exclusive with `country`/`state`/`city` (`400`). Fixed-location-only suppliers have no zone and are not matched by a point. The first way to ask "who covers this address?" without a service and an offering.
* **Borough matching.** Coverage now resolves to the locality, its borough and the wider municipality, so a Scarborough zone is returned by `city=Scarborough` **and** `city=Toronto`. Previously only the municipality matched.
* **`locale` on `POST /v1/projects/{projectId}/orders`** — optional, the language the buyer completed the purchase in. Normalized to canonical BCP-47 (`en-us` → `en-US`); malformed is a `400 VALIDATION_ERROR`. Immutable on the order, snapshotted as `locale` onto every booking the order funds (never accepted on `POST /bookings`), and saved as the client's `defaultLocale` (latest booking wins). Suppliers gain a staff-set `defaultLocale` on create and update (`null` clears on update) and in every response — distinct from the existing `languages` and derived `locales`.
* **Three review-URL tokens** beside `{bookingId}`: `{bookingLocale}`, `{clientLocale}`, `{supplierLocale}`. Each falls back only to the project default, never to another token. See [Emails](https://docs.gomarketbox.com/concepts/emails.md#where-the-rating-links-go).

**Changed**

* **One schedule-liveness rule.** A schedule is live when it is `ACTIVE`, not deleted, **and its `endDate` has not passed in the schedule's own timezone**. `locations[]`, the region filter, `servedRegions` and the detail endpoint's `availability.schedules` all use it. Before this release `locations[]` and `availability.schedules` ignored `endDate`, so a supplier whose only schedule had ended still advertised a travel zone the filter no longer matched — in one real project, 80 records carried `country: "CA"` on their profile while `?country=CA` returned 49 rows. **`locations[]` and `availability.schedules` can now be shorter, including `[]`, for suppliers you saw as bookable yesterday.**
* **Supplier `phone` is validated and normalized.** Create and update accept E.164 or a national NANP number and store E.164 (`+14165550134`); anything unparseable is a `400 VALIDATION_ERROR`. Update accepts `null` to clear. Rows written before this release keep whatever was typed until next edited.

**What this means for you**

* **Regenerate response types.** `servedRegions: string[]` is required everywhere a supplier is returned.
* **Stop deriving "does this supplier serve Toronto?" from profile `city`/`state`.** Read `servedRegions`, or use the filter — they agree by construction. `locations[]` is per-request; `servedRegions` is swept daily and can lag a schedule's `endDate` by up to a day.
* **If you filter by `city`, expect more rows** where boroughs exist. Nothing you matched before stopped matching.
* **If you cached `locations[]` to decide bookability**, refresh: a schedule past its `endDate` no longer contributes. `schedules: []` on the detail endpoint now really means "cannot be booked".
* **Send `locale` on order create** if your storefront is localized and you use a review redirect URL — it is the only way MarketBox can learn the language, and the tokens fall back to the project default without it.
* **Don't pre-format phones**, and don't assume the stored value matches what you sent — read it back.

Full detail: [Suppliers → Regions served](https://docs.gomarketbox.com/resources/suppliers.md#regions-served), [Listing suppliers](https://docs.gomarketbox.com/resources/suppliers.md#listing-suppliers), [Orders → Creating an order](https://docs.gomarketbox.com/resources/orders.md#creating-an-order).

**August 26, 2026**

## Every slate now says why it isn't a perfect match: `matchNotes` and `advice`

`matchScore` told you how well a slate matched, and `matchComponents` told you which criterion missed. Neither told you **why** — so a booking UI could show "3 of 4 weeks" and had nothing to put underneath it. Slates now carry `matchNotes`: one coded reason per departure, each with the evidence behind it.

**Purely additive.** No existing field changed shape, meaning, or gating. Every request valid before this release is still valid, and every response field you already read is unchanged. This one is safe to adopt at your own pace — unlike the `cadenceSummary` release below it, which removed a field.

**New**

* **`matchNotes` on every slate** (`PackageSlateDto`) — an array of `{ code, component, weekStart?, evidence }` objects. **Always present**: nothing departed from your request means `[]`, not a missing key, so `.length` is safe to read without a null check. It is **not** gated on `matchScore` — a `DIRECT_FILL` slate and a `PARTIAL` slate can both score `1` and still carry notes, and those are exactly the slates worth captioning.

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

* **Nine codes**, each with its own evidence shape, discriminated on `code` so your generated types tell you exactly which fields are present: `SUPPLIER_UNAVAILABLE_WEEK`, `WEEK_EXCLUDED_BY_FILTERS`, `WEEK_SUPPLY_INSUFFICIENT`, `WEEK_CAPPED`, `SESSIONS_EXHAUSTED`, `CADENCE_RELAXED`, `SESSIONS_OUTSIDE_PREFERRED_TIMES`, `FIRST_SESSION_LATE`, `PACKAGE_UNDERFILLED`.
* **`advice` on every slate**, optional — a forward-looking hint naming `earliestSustainedWeek`, the earliest Monday from which supply alone could sustain the frequency you asked for.
* Both fields appear at **all 17 slate positions** across the same four operations `cadenceSummary` reaches: `POST /v1/projects/{projectId}/availability/package-slate` (`200`), `POST /v1/projects/{projectId}/availability/package-options` (`200`), `POST /v1/projects/{projectId}/orders/{orderId}/package-bookings` (**`409`**, inside `freshSuggestions`), and `POST /v1/projects/{projectId}/suggestions/slots/{slotId}/reschedule` (`200` and **`409`**).

**Why there is no message string**

A note carries no English at all. You keep your own copy and can localise it; `evidence` exists so you can name the week, the weekday or the count in your own wording. Weekday numbers everywhere are `0` = Sunday through `6` = Saturday, matching request-level `daysOfWeek`.

**What this means for you**

* **"Wait a week" and "loosen your days" are opposite calls to action, and telling them apart is the point of the whole field.** The supplier-break case reaches you as `WEEK_SUPPLY_INSUFFICIENT` with `openingsInPool: 0` — nothing was open that week, relaxing your own filter cannot help, so "wait a week" is the honest thing to say and `advice` names which week. `WEEK_EXCLUDED_BY_FILTERS` is the reverse: the supplier's working pattern covers days in that week and your `daysOfWeek` or `excludeDates` cut them below your target, so "loosen your days" is the move. The candidate pool alone can't separate them, because your filters were already applied to it; `evidence.supplierWorkdays` is the pre-filter fact that can. Note it is a fact about the supplier's working **pattern**, not a check of that calendar week, so treat "loosen your filter" as the most likely fix rather than a guaranteed one.
* **`SUPPLIER_UNAVAILABLE_WEEK` is published but not currently emitted by the live engine.** It fires only for a supplier who works no weekday at all, and such a supplier yields no availability and therefore no slate for a note to attach to. Keep it in your `switch` — it is part of the contract — but key your "waiting helps" copy on `WEEK_SUPPLY_INSUFFICIENT` with `openingsInPool: 0` instead.
* **`SESSIONS_EXHAUSTED` means nothing went wrong — don't apologise for it.** Nine sessions at four a week leaves the last week holding one. That week is short because the package ran out of credits, not because anyone failed. It outranks every supply code, so when it's emitted for a week no supply code is emitted for that same week. Render it as a plain fact or drop it; surfacing it as a problem makes correct behaviour look broken.
* **`advice` is advisory and nothing more.** It reports that open supply exists from `earliestSustainedWeek` onward — **not** that a slate was built for that week, and not that one would be bookable. Holds, capacity, travel time and the cadence rules all still apply. Re-request with a later `lookAheadStartDate` before promising a client anything.
* **`matchNotes` explains `matchComponents`, it doesn't replace it.** Read `matchComponents` for *which* criterion missed and `matchNotes` for *why*; `component` on each note points at the criterion it explains. `PACKAGE_UNDERFILLED` is the one code with no `component`, because plan size isn't a scored criterion. That pointer is a guide, not a join key: the week-level codes bucket **Monday-anchored calendar weeks** while `matchComponents.sessionsPerWeek` buckets **consecutive 7-day blocks from your window's start**, so a note can name a short week for a criterion the component scores as met, and the reverse. Join notes to `cadenceSummary.byWeek` on `weekStart`, which shares their bucketing.
* Slates persisted before this release read back with `matchNotes: []` and no `advice`. Both are provenance — recorded when the slate was built, not re-derived on a rebuild.

Full walkthrough, with both sides of the supplier-versus-filter pair side by side: [Suggestions → Why a slate departs from your request](https://docs.gomarketbox.com/resources/suggestions.md#why-a-slate-departs-from-your-request-matchnotes).

**August 26, 2026**

## Slate cadence: `sessionsPerWeek` is gone, `cadenceSummary` replaces it

Every slate now reports how often it actually runs, week by week, instead of a single averaged rate.

**Breaking**

`sessionsPerWeek` has been **removed from the slate object** (`PackageSlateDto`) and replaced by `cadenceSummary`. This is only the slate *response* field: the request field of the same name (integer `1`–`14`, the frequency target) and `matchComponents.sessionsPerWeek` (the `0`–`1` match ratio) are **unchanged and still present**.

Before:

```json theme={null}
{
  "slateId": "slate_01kx16ejsqffc9rbgdcc591w2p",
  "cadenceRrule": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH;COUNT=9",
  "sessionsPerWeek": 1.67
}
```

After:

```json theme={null}
{
  "slateId": "slate_01kx16ejsqffc9rbgdcc591w2p",
  "cadenceRrule": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH;COUNT=9",
  "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 }
    ]
  }
}
```

**Why**

The removed field was an average, and an average is the one number that describes none of the weeks. When a supplier takes a week off mid-plan, a nine-session plan lands 1 / 0 / 4 / 4 across four weeks — so the field reported `1.67`, and booking UIs rendered "1.67×/week" for a plan that runs at four a week wherever it runs at all. There was no way to recover the real cadence from that number, and no way to see *which* week was short.

`cadenceSummary` publishes the week-by-week truth instead. `peak` is the most sessions in any one week and is **the number to render**. `average` is `byWeek`'s sessions divided by `byWeek`'s length to two decimal places, verifiable straight from the array, counted across the plan's own span (first session's week through last session's) rather than your whole look-ahead window, so a wide window doesn't dilute it. `byWeek` is Monday-anchored, ascending and contiguous, and **includes weeks holding `0` sessions** — the zero week is how you show a client why a plan looks uneven instead of apologising for it. `requested` echoes the frequency you asked for: your `sessionsPerWeek` target when you sent one, otherwise the number of weekdays your own `FREQ=WEEKLY` rule named in `BYDAY`, and `null` 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 for you).

**Changed**

* **Gating is wider than the field it replaces.** `sessionsPerWeek` was stamped only when cadence relaxation had been requested, so a strict caller could not get a cadence number at all. `cadenceSummary` is present on **every** request path, including the default `cadenceFlexibility: "NONE"`. It is absent only for a slate holding no sessions, which has no cadence to describe.
* **The swap spans 17 response positions across four operations**, not just the obvious one — every place a slate is published:
  * `POST /v1/projects/{projectId}/availability/package-slate` — `200`: `primarySlate`, `alternates[]`, `partial`, `cadenceAlternatives[]`.
  * `POST /v1/projects/{projectId}/availability/package-options` — `200`: the same four inside each entry of `data[]`.
  * `POST /v1/projects/{projectId}/orders/{orderId}/package-bookings` — **`409`**: the same four inside `freshSuggestions`.
  * `POST /v1/projects/{projectId}/suggestions/slots/{slotId}/reschedule` — `200`: `slate`. **`409`**: the same four inside `freshSuggestions`.

**What this means for you**

* **Read `cadenceSummary.peak` wherever you read `sessionsPerWeek`, and render `peak`.** Don't substitute `average` — that reproduces the bug this release fixes.
* **Update the `409` paths too, not just the availability calls.** Those bodies fire mid-checkout, when a slot went stale while a client was paying, and their `freshSuggestions` carries full slates. A client that reads the removed field only on the happy path fails at the worst possible moment.
* **`cadenceSummary` and `matchComponents.sessionsPerWeek` count weeks differently, deliberately.** `cadenceSummary` buckets Monday-anchored calendar weeks, so `weekStart` is always a real Monday and the buckets agree with the `maxSessionsPerWeek` cap. The `matchComponents` ratio buckets consecutive 7-day blocks from your window's start, so it stays comparable with `availabilityMatch` on `POST /availability/suppliers`. `peak: 4` against a target of `4` while that ratio reads below `1` is exactly the supplier-break case above, and both numbers are correct for what they measure — not a bug.
* **Unlike its neighbours, `cadenceSummary` is not provenance.** `matchScore` and `matchComponents` are recorded once and never re-derived, but `peak`, `average` and `byWeek` recompute from the slate's current sessions on every rebuild; only `requested` is snapshotted. A slate can come back from a reschedule with an unchanged `matchScore` and a changed `cadenceSummary`.
* Slates persisted before this release read back with `requested: null`; `peak`, `average` and `byWeek` are computed from their stored sessions, so they are correct.

Full explanation, with the two week-bucketings side by side: [Suggestions → How often a plan runs](https://docs.gomarketbox.com/resources/suggestions.md#how-often-a-plan-runs-cadencesummary).

**July 14, 2026**

## Package discovery, bookable package options, and a wider look-ahead window

Packages are now discoverable and plannable in one call each — and the weekly multi-session package that the engine used to refuse is bookable.

**New**

* **`GET /v1/projects/{projectId}/services/{serviceId}/packages`** — every package on a service, **across all of its offerings**. This is the call a storefront makes *before* the client picks an option, when it holds a `serviceId` and no `offeringId` — previously there was no endpoint that could answer it. Pass `?status=ACTIVE` for just the purchasable bundles. Each package carries its `offeringId`, so you can join it against the offerings list you already hold. A real service that sells no packages is a `200` with `data: []`; an **unknown** `serviceId` is a `404`, so a typo can never masquerade as "no packages".
* **`POST /v1/projects/{projectId}/availability/package-options`** — every ACTIVE package of a service, each planned against a supplier's real availability and carrying a ready-to-book `slateId`. Send a `serviceId` and a location (`locationId`, or `lat` + `lng` + `address`); `supplierId`, `timezone`, and `rrule` are optional. Cadence defaults to `FREQ=WEEKLY;COUNT={creditCount}`, derived **per package** from its own credit count. It replaces the client-side fan-out of one `package-slate` call per package, and it's cheaper than that loop — supplier bundles are read once per offering, not once per package.

**Changed**

* **The package look-ahead ceiling moved from 31 days to 120 days.** The window is still derived from your cadence and the package's `creditCount` — only the cap on that derivation changed. A weekly 10-session package spans about 70 days, so it was **unbookable** under the old 31-day cap and always came back `NO_COMPLETE_SLATE`; it now plans and books normally, as do weekly 12-packs (\~84 days) and biweekly 5-packs (\~70 days). A cadence that still needs more than 120 days keeps the existing fail-loud behaviour — `NO_COMPLETE_SLATE` with a `reason` naming the exact window required, never a silently truncated slate.

**What this means for you**

* If you were listing **business models** and rendering each row as a package, stop. `PACKAGE` is a business model — a flag meaning "this service *can* be sold as packages" — not a sellable bundle, and it carries no `creditCount` and no `pricing`. The bundles are what the new package list returns.
* If you hardcoded a dense weekday `rrule` (e.g. `FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR`) purely to squeeze a multi-session package under the 31-day cap, you can drop the workaround and send the cadence you actually sell.
* Purely additive: no existing route, schema, or DTO changed shape. Every request valid before this release is still valid.

Walkthroughs: [Create a package booking with a slate](https://docs.gomarketbox.com/guides/create-a-package-booking.md) (now starts at finding the package) and [Availability and slates](https://docs.gomarketbox.com/guides/availability-and-slates.md) for the cadence rules and the new ceiling.

**July 13, 2026**

## Holds, the double-booking guard — and a breaking change to `POST /holds`

Supplier time is now exclusive at the write layer, and you can **hold** it while a client pays. A hold works on any supplier time — a single session (no package, no slate), a cherry-picked subset of a package slate, or a whole slate — and `POST /holds/{reservationId}/convert` turns it into confirmed bookings. Alongside it, every write that claims supplier time now passes through an occupancy guard, so two bookings can never overlap on the same supplier.

**Breaking**

Each entry in `intervals[]` on `POST /v1/projects/{projectId}/holds` now mirrors the `POST /bookings` location contract exactly. **`bookingTz` and `locationType` are required**, and `locationType` decides which of `locationId` / `latitude` / `longitude` / `address` must come with them.

Before:

```json theme={null}
{
  "intervals": [
    {
      "supplierId": "sup_01kv60qgnef2kt3pvqgwmkbzfr",
      "startUtc": "2026-07-15T14:00:00.000Z",
      "endUtc": "2026-07-15T15:00:00.000Z",
      "locationId": "stz_01kv60qgs4e4nbjhzradnqtj0h"
    }
  ]
}
```

After:

```json theme={null}
{
  "intervals": [
    {
      "supplierId": "sup_01kv60qgnef2kt3pvqgwmkbzfr",
      "startUtc": "2026-07-15T14:00:00.000Z",
      "endUtc": "2026-07-15T15:00:00.000Z",
      "bookingTz": "America/Toronto",
      "locationType": "TRAVEL_ZONE",
      "locationId": "stz_01kv60qgs4e4nbjhzradnqtj0h",
      "latitude": 43.6532,
      "longitude": -79.3832,
      "address": {
        "addressOneLine": "100 Queen St W, Toronto, ON M5H 2N2, Canada",
        "streetNumber": "100",
        "streetName": "Queen St W",
        "city": "Toronto",
        "state": "ON",
        "country": "CA",
        "zipCode": "M5H 2N2"
      }
    }
  ]
}
```

An interval without `bookingTz` or `locationType` is now a `400 VALIDATION_ERROR`. This applies to the heartbeat too — extending a hold re-sends the same `intervals`, so they must carry the same fields.

**Why**

Convert rebuilds the booking from the **reservation alone** — never by re-reading a slate that may have expired while the client was paying. A hold that carried only a `locationId` could not say whether that id was a `Location` (`loc_…`) or a supplier travel zone (`stz_…`), so converting a mobile / in-home hold failed with `404 Location stz_… not found`, and a `TRAVEL_ZONE` booking's mandatory coordinates and address were never held at all. Travel-zone checkouts now work end to end.

**New**

* **`POST /holds`** — hold supplier time with `intervals` (single session or any explicit time), `slateId` (a whole package slate), or `slotIds` (a subset). All-or-nothing, in one transaction. Pass `reservationId` to **extend** an existing hold: the checkout heartbeat pushes `heldUntil` out and returns the same `reservationId` instead of minting a second hold.
* **`POST /holds/{reservationId}/convert`** — one idempotent endpoint for both shapes; it branches on the order item's `skuType` (`SINGLE_SESSION` books the one held interval; `PACKAGE` books every held interval and draws down credits). Safe to call straight from a Stripe webhook. (The public API sends no webhooks of its own; see [Hold slots during checkout](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md) for when to convert.)
* **`GET /holds/{reservationId}`** and the `201` from `POST /holds` now **echo the full interval shape** — `bookingTz`, `locationType`, `locationId`, `latitude`, `longitude`, `address` — so you can verify exactly what convert will build.
* **`POST /holds/{reservationId}/release`** — free the time immediately when a checkout is abandoned. Idempotent, never an error.
* **Occupancy guard** — `409 SLOT_HELD` / `SLOT_BOOKED` on any write that collides with a live claim. The body names the blocking `reservationId` or `bookingId` and tells you what to do with it.
* **Conflict responses now carry the full error envelope.** Every `409` conflict and hold-lifecycle body (`SLOT_HELD`, `SLOT_BOOKED`, `HOLD_EXPIRED`, `RESERVATION_*`, and the slate codes) now includes `statusCode` and `requestId` alongside `code` and `message`, matching every other error. Purely additive — nothing was removed or renamed. If you were branching on the HTTP status because `body.statusCode` was missing on these, you no longer have to. See [Errors](https://docs.gomarketbox.com/concepts/errors.md).

**What this means for you**

* If you build `intervals` by hand, **add `bookingTz` and `locationType` before your next deploy** — including in your heartbeat call.
* If you hold by `slateId` or `slotIds`, **nothing changes**: the slate's slots already carry every location field, and the hold now copies them onto the reservation for you.
* If you hold time, you must **convert** it — `POST /bookings` and `POST /orders/{orderId}/package-bookings` will not consume a hold, not even your own, and return `409 SLOT_HELD` naming your own `reservationId`.

Full walkthrough, a travel-zone worked example, and a status/code troubleshooting table: [Hold slots during checkout](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md). The guard itself: [Concurrency](https://docs.gomarketbox.com/concepts/concurrency.md).

**May 29, 2026**

## Catalog management endpoints

You can now manage your service catalog directly through the API. This release adds full create, read, update, and delete (CRUD) support for services, their offerings, and the business models attached to them — so you can build, sync, and automate catalogs without using the dashboard.

**New**

* **Services** — Create, list, retrieve, update, soft-delete, and toggle status for services on a project. See [Services](https://docs.gomarketbox.com/api-reference/introduction.md).
* **Offerings** — Add offerings to a service, list them, fetch a single offering, update or soft-delete it, and change its status.
* **Business models** — Attach pricing/business models to a service, list them, update them, and toggle active status.

**What this means for you**

* Sync your catalog from an external system of record on a schedule.
* Build admin tooling that lives outside the MarketBox dashboard.
* Programmatically enable or disable offerings as inventory and availability shift.

All new endpoints are project-scoped and follow the existing [authentication](https://docs.gomarketbox.com/concepts/authentication.md), [pagination](https://docs.gomarketbox.com/concepts/pagination.md), and [error](https://docs.gomarketbox.com/concepts/errors.md) conventions. Browse the full list under [API reference → Endpoints](https://docs.gomarketbox.com/api-reference/introduction.md).


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