Skip to main content
POST
Hold supplier time during checkout — a single session, or a whole package slate

Authorizations

x-api-key
string
header
required

API key minted in the MarketBox dashboard. Scope is restricted to the projects you select at creation time. Every route needs the key's standard API access (*) except POST /v1/projects/{projectId}/events, which needs events:write; a key without * is refused with 403 CAPABILITY_NOT_GRANTED.

Path Parameters

projectId
string
required

The project the hold belongs to.

Minimum string length: 1
Example:

"prj_01kv60qgnef2kt3pvqgwmkbzfr"

Body

application/json

intervals | slateId | slotIds (+ optional reservationId to extend, heldBy, holdDurationMins)

intervals
object[]

Explicit supplier time to hold. Use this for a single session — no package or slate required.

Minimum array length: 1
slateId
string

Hold every slot of a persisted package slate (from POST /availability/package-slate).

Minimum string length: 1
Example:

"slate_01kv7n10k0fnptwk81wkm59vj7"

slotIds
string[]

Cherry-pick individual slots of a slate to hold.

Minimum array length: 1
Minimum string length: 1
reservationId
string

EXTEND an existing hold instead of minting a new one — this is the checkout HEARTBEAT. Supply the reservationId a previous POST /holds handed you: heldUntil is pushed out, the hold keeps its original createdAt, the SAME claim stays on the supplier calendar (no second hold is minted), and the SAME reservationId comes back — so the id you convert later is still the right one. The intervals you send must be the ones that hold already claims, and heldBy must match the hold's owner. A mismatch is 409 RESERVATION_FORBIDDEN; an unknown id is 409 RESERVATION_NOT_FOUND; an already converted/released hold is 409 RESERVATION_NOT_HELD. Omit this field to mint a NEW hold.

Minimum string length: 1
Example:

"resv_01kv8p20m1gnqvxl92xln6awk8"

heldBy
string

Who owns the hold — typically your checkout session id. Re-holding time you already hold under the same heldBy does not conflict with your own hold; to actually EXTEND that hold (the checkout heartbeat) pass its reservationId as well, otherwise a new hold is minted. Defaults to the API principal.

Minimum string length: 1
Example:

"checkout_9f2c1b"

holdDurationMins
integer

How long to hold, in minutes. Defaults to the offering override, then the project default, then 5.

Required range: x > 0
Example:

10

Response

Hold placed — supplier time is now claimed until heldUntil

reservationId
string
required
Example:

"resv_01kv8p20m1gnqvxl92xln6awk8"

status
enum<string>
required
Available options:
HELD,
CONVERTED,
RELEASED
heldUntil
string<date-time>
required

When the hold lapses. Expiry is LAZY — nothing runs at this instant; the hold simply stops blocking. Convert before this time.

Example:

"2026-07-10T12:05:00.000Z"

intervals
object[]
required