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

# Concurrency and versioning

> Supplier time is exclusive — how MarketBox guards against double-booking, and what to do when you hit a 409.

Two things in this API can race, and they are guarded differently.

**A supplier's time is exclusive.** Two bookings can't overlap on the
same supplier, and every write that claims supplier time — a booking, a
package booking, a hold, a reschedule, a hold conversion — passes through
an **occupancy guard** that enforces it transactionally. If two callers
race for the same time, exactly one wins; the other gets a `409` naming
what blocked it. (The guard is on for every project by default; see
[When the guard is off](#when-the-guard-is-off) for the one exception.)

**Everything else is optimistic.** Mutable resources (bookings, orders,
order items) carry a numeric `version` that advances on every write. If
two writers race on the same record, one wins and the other gets
`409 VERSION_CONFLICT`.

## Supplier-time exclusivity

Time on a supplier's calendar can be claimed by exactly one of two things:

* a **booking** — blocks that time permanently (until cancelled);
* a **hold** — blocks that time until its `heldUntil` passes. See
  [Hold slots during checkout](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md).

The guard runs inside the same transaction as the booking write, so
there is no window between "we checked" and "we wrote". Two concurrent
`POST /bookings` for the same supplier at the same instant produce exactly
one booking and one `409` — never two bookings (unless the
[guard is off](#when-the-guard-is-off) for your project), and never a
half-written package.

> [!NOTE]
>
> The guard enforces **hard interval exclusivity** only. Travel buffers,
> travel-time clashes, and working hours are enforced by the availability
> engine on the read side, when you search. The write guard is the safety net
> underneath: it is what makes a physically impossible schedule
> unrepresentable, even if you book by hand without searching first.

### When the guard is off

A project setting, `suggestionConfig.enforceOccupancyGuard`, can switch the
guard off. It defaults to `true`. It is set in the project's settings, and
the public API can't read or change it. With the guard off,
`POST /bookings` and `POST .../package-bookings` write bookings without
checking or claiming supplier time. They never return `SLOT_BOOKED` or
`SLOT_HELD`, and two of them can overlap. Holds, hold conversions and
reschedules still check. If you see overlapping bookings on one supplier,
check whether the setting is off for your project.

### Intervals are half-open

An interval is `[startUtc, endUtc)` — the start is inclusive, the end is
exclusive. **Back-to-back bookings do not collide.** A session ending at
`15:00:00Z` and one starting at `15:00:00Z` are both bookable on the same
supplier:

```
10:00 ──────── 11:00        booked
               11:00 ──────── 12:00   ✅ also bookable — no overlap
        10:30 ──────── 11:30          ❌ 409 — overlaps the first
```

Times are arbitrary minute precision — there is no 15-minute grid. A
booking from `10:07` to `10:52` blocks exactly `10:07`–`10:52`.

## The three supplier-time conflicts

All three are `409`, and all three tell you exactly what is in the way.

### `SLOT_BOOKED`

A confirmed booking already occupies the time. `conflicts[]` names the
blocking `bookingId`.

```json theme={null}
{
  "code": "SLOT_BOOKED",
  "message": "Supplier time is not available: BOOKING bk_01k16f2a0e5x9jv6r0c1qs7pm (2026-07-15T14:00:00.000Z–2026-07-15T15:00:00.000Z)",
  "statusCode": 409,
  "requestId": "1c8e4a6f-3d2b-4f97-a5e1-0b9d7c3f6a24",
  "conflicts": [
    {
      "claimType": "BOOKING",
      "startUtc": "2026-07-15T14:00:00.000Z",
      "endUtc": "2026-07-15T15:00:00.000Z",
      "reservationId": null,
      "bookingId": "bk_01k16f2a0e5x9jv6r0c1qs7pm",
      "heldUntil": null,
      "supplierId": "sup_01kv60qge5eh59ap0gw0pqrrys"
    }
  ],
  "hint": "This supplier is already booked for the requested time. Search availability again."
}
```

Not retryable — the time is gone. Search availability again and offer
something else.

### `SLOT_HELD`

A **live hold** occupies the time, and `conflicts[]` names the blocking
`reservationId` plus the `heldUntil` at which it lapses.

Most often, the hold is **your own**: you held the time for a checkout and
then called `POST /bookings` (or `POST .../package-bookings`) directly.
The direct booking routes never consume a hold — **if you hold, you
convert**. Take the `reservationId` out of the response and call
`POST /holds/{reservationId}/convert` instead. If the hold belongs to
someone else's checkout, `heldUntil` tells you when the time frees up.

The full body and both branches are in
[Hold slots during checkout](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md#handling-a-held-slot).

### `OCCUPANCY_CONTENTION`

Not a conflict over *your* time — a conflict over the *row*. Claims are
guarded per supplier per UTC day with an optimistic version, and several
writers hammering the same supplier-day serialize. The API retries
internally; `OCCUPANCY_CONTENTION` means even the bounded retry gave up.

This one **is** retryable. Re-send the same request after a short backoff
(50–200 ms, jittered). On a hold release, the hold is still `HELD` after this
`409`, so retry the release. Two people booking *different* times with the same
supplier on the same day normally both succeed — you should see this code
only under genuinely heavy contention.

> [!WARNING]
>
> Holds also block **search**. A held slot is not returned as available by
> `/availability/search` or `/availability/package-slate` while its hold is
> live. A slot that disappears between two searches may simply be mid-checkout
> for someone else — it will come back if their hold lapses.

## Optimistic versioning on updates

Every booking, order, and order item DTO includes a numeric `version`:

```json theme={null}
{
  "bookingId": "bk_...",
  "version": 4,
  "status": "SCHEDULED"
}
```

You don't have to track it manually — the server reads the current version
on each PATCH/DELETE and applies your update atomically. But you'll see it
move when something changes, and you'll get `409 VERSION_CONFLICT` when two
writers race, or when you read, sat on the result, and then patched a
record that had since advanced.

### Recovering

1. **GET** the resource again — you'll see the new `version` and the
   current state.
2. **Reapply** your change on top of the fresh state. If the new state
   makes your update irrelevant (someone else already cancelled the booking
   you were about to cancel), skip the retry.
3. **PATCH** again.

```ts theme={null}
async function rescheduleWithRetry(projectId: string, bookingId: string, patch: Patch) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const res = await fetch(`/v1/projects/${projectId}/bookings/${bookingId}`, {
      method: 'PATCH',
      headers: { 'x-api-key': KEY, 'content-type': 'application/json' },
      body: JSON.stringify(patch),
    });
    if (res.status !== 409) return res;

    const fresh = await (await fetch(`/v1/projects/${projectId}/bookings/${bookingId}`)).json();
    if (alreadyDone(fresh.data, patch)) return fresh;
  }
  throw new Error('Too many version conflicts');
}
```

Note that a **reschedule** passes through the occupancy guard as well as
the version check: moving a booking onto time that someone else holds or
has booked returns `SLOT_HELD` / `SLOT_BOOKED`, not `VERSION_CONFLICT`.

## Where you'll see 409

| Endpoint | Can 409? |
| - | - |
| `POST /v1/projects/{projectId}/bookings` | Yes — `SLOT_BOOKED`, `SLOT_HELD`, or `OCCUPANCY_CONTENTION`. |
| `POST /v1/projects/{projectId}/orders/{orderId}/package-bookings` | Yes — same three, plus stale-slot and credit conflicts. |
| `POST /v1/projects/{projectId}/holds` | Yes — `SLOT_BOOKED` / `SLOT_HELD` when the time is already claimed by someone else, or `RESERVATION_NOT_FOUND` / `RESERVATION_NOT_HELD` / `RESERVATION_FORBIDDEN` when extending a hold with a `reservationId` that is unknown, no longer held, or not yours. |
| `POST /v1/projects/{projectId}/holds/{reservationId}/convert` | Yes — `HOLD_EXPIRED`, `SLOT_BOOKED` / `SLOT_HELD` if the time went while you were paying, or `OCCUPANCY_CONTENTION`. |
| `POST /v1/projects/{projectId}/holds/{reservationId}/release` | Yes — `OCCUPANCY_CONTENTION` only. The hold is still `HELD`, so retry the release. |
| `PATCH /v1/projects/{projectId}/bookings/{bookingId}` | Yes — `VERSION_CONFLICT`, `SLOT_BOOKED` / `SLOT_HELD` on a reschedule (with `conflicts[]` and `hint`), or `OCCUPANCY_CONTENTION`. |
| `PATCH /v1/projects/{projectId}/suppliers/me/bookings/{bookingId}` | Yes — `VERSION_CONFLICT`, `SLOT_UNAVAILABLE`, `OCCUPANCY_CONTENTION`, and the notice-window and status refusals. |
| `PATCH` and `DELETE` on `.../suppliers/me/schedules/{scheduleId}`, `/blocked-times/{blockedTimeId}` and `/travel-zones/{travelZoneId}` | Yes — `VERSION_CONFLICT` for a stale `version`, or another write during a `DELETE`. A schedule overlap is `CONFLICT`. |
| `POST /v1/projects/{projectId}/bookings/{bookingId}/status` | Yes — booking version moved. |
| `DELETE /v1/projects/{projectId}/bookings/{bookingId}` | Yes — booking version moved. |
| `PATCH /v1/projects/{projectId}/orders/{orderId}` | Yes — order version moved. |
| `POST /v1/projects/{projectId}/orders/{orderId}/status` | Yes — order version moved. |
| `DELETE /v1/projects/{projectId}/orders/{orderId}` | Yes — order version moved, or `ORDER_NOT_DELETABLE` when the order holds a booking or money. |
| `POST /v1/projects/{projectId}/bookings/{bookingId}/participants` | Yes — `CONFLICT` (booking at capacity, or the client is already registered). |
| `PUT /v1/projects/{projectId}/suppliers/{supplierId}` | Yes — `CONFLICT` for a duplicate email, or when you sent `active` and it changed between the update's read and its write. Read the supplier again and retry. |
| `PUT` and `DELETE` on `.../suppliers/{supplierId}/avatar` and `.../suppliers/me/avatar` | Yes — `CONFLICT` when another confirm or remove changed the photo while this one was being saved. Read the supplier again and retry. |

## Capacity and duplicate conflicts

`409` also covers business-level conflicts that are neither version-based
nor supplier-time-based — both return the generic `CONFLICT` code:

* **Booking at capacity** — registering a participant would put the booking
  past its `capacity`. The booking's version is unchanged.
* **Duplicate participant** — the client is already on the
  participant list (and not in a cancelled state).

These aren't fixable by re-reading and retrying — the action just can't
proceed. Surface them to the user rather than looping.

## Which 409s are retryable

| `code` | Retry the same request? |
| - | - |
| `OCCUPANCY_CONTENTION` | **Yes** — short backoff. Transient row contention. |
| `VERSION_CONFLICT` | Re-read first, reapply, then retry. |
| `SLOT_HELD` | **No** — convert the named `reservationId`, or offer another slot. |
| `SLOT_BOOKED` | **No** — the time is taken. Search again. |
| `HOLD_EXPIRED` | **No** — hold again, then convert the new reservation. |
| `CONFLICT` (booking at capacity, duplicate participant, or overlapping schedule) | **No** — surface to the user. |
| `CONFLICT` (a supplier's `active` or photo changed during your write) | Re-read the supplier first, then retry. |

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


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