Skip to main content
POST
Book sessions from the authenticated client's own package credit

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.

Authorization
string
header
required

The signed-in person's Cognito access token, issued to this application's app client. Sent with the API key on the /clients/me and /suppliers/me routes.

Path Parameters

projectId
string
required

The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.

Minimum string length: 1
Example:

"prj_01kv60qgnef2kt3pvqgwmkbzfr"

orderId
string
required

The order — the commercial record. Order items are drawn down into bookings.

Minimum string length: 1
Example:

"ord_01kv8m92p4jcrywn14znp8cym0"

Body

application/json

Order item + sessions + atomicity

orderItemId
string
required

The PACKAGE order item to draw down. All N sessions decrement its quantityRemaining.

Minimum string length: 1
Example:

"oi_01kx16ek2kf2fsc9x7b2n1dfc9"

idempotencyKey
string
required

Idempotency key that makes retry attempts safe; reusing it returns the original result. A slateId/slotIds retry must arrive within the slate's resolvable window; after that it is refused like a stale slate.

Minimum string length: 1
Example:

"a3f1c2e4-5b6d-4e7f-8a9b-0c1d2e3f4a5b"

atomicity
enum<string>
default:all_or_nothing

all_or_nothing (default, one transaction, max 15 sessions) or best_effort (per-session; requires project opt-in).

Available options:
all_or_nothing,
best_effort
Example:

"all_or_nothing"

sessions
object[]

Explicit, client-supplied sessions (advanced). Prefer slateId. Provide exactly one of sessions, slateId, or slotIds.

Minimum array length: 1
slateId
string

Book an entire persisted slate by id (recommended). The server resolves every session; send no session details.

Minimum string length: 1
Example:

"slate_01kx16ejsqffc9rbgdcc591w2p"

slotIds
string[]

Cherry-pick specific persisted slots by id. Provide exactly one of sessions, slateId, or slotIds.

Minimum array length: 1
Minimum string length: 1
Example:

Response

Package bookings created

orderId
string
required
orderItemId
string
required
packageOrderItemId
string
required
atomicity
enum<string>
required
Available options:
all_or_nothing,
best_effort
created
object[]
required

Bookings created, each with a 0-based sessionIndex, bookingId and allocationId.

failed
object[]
required

Per-session failures (best_effort only).

quantityRemaining
integer
required

Credits left on the order item after this call.

Required range: x >= 0