Skip to main content
POST
Convert a hold into confirmed bookings (the idempotent purchase hook)

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"

reservationId
string
required

The reservationId returned by POST /holds.

Minimum string length: 1
Example:

"resv_01kv8p20m1gnqvxl92xln6awk8"

Body

application/json

orderId + orderItemId (+ optional heldBy, atomicity)

orderId
string
required

The order whose item the bookings draw credits from.

Minimum string length: 1
Example:

"ord_01kv7n10k0fnptwk81wkm59vj7"

orderItemId
string
required

The order item to draw down. For a multi-session hold this must be a PACKAGE item with enough quantityRemaining.

Minimum string length: 1
Example:

"oi_01kv7n10k0fnptwk81wkm59vj7"

heldBy
string

Required to match if the hold was created with a heldBy.

Minimum string length: 1
atomicity
enum<string>
default:all_or_nothing

all_or_nothing (default) books every session in one transaction. best_effort requires suggestionConfig.allowPartialPackages.

Available options:
all_or_nothing,
best_effort

Response

Hold converted to confirmed bookings

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