Skip to main content
POST
Create a new order

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 (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"

Body

application/json

Order data

clientId
string
required

The client placing the order.

Minimum string length: 1
Example:

"cli_01kv8p20m1gnqvxl92xln6awk8"

currency
string
required

ISO 4217 currency you quoted the buyer. Verified against the price the server resolves for this order's region; a mismatch is a 400.

Required string length: 3
Example:

"CAD"

locale
string

The locale your buyer completed this purchase in — typically the language segment of your storefront URL. Normalized to canonical BCP-47 on write, so en-us is stored as en-US. It is copied onto every booking this order funds and saved as the client's default locale.

Example:

"en-US"

attribution
object

Which search and site session this purchase came from: the searchId of the search response the buyer booked from, your opaque sessionKey, and the surface the list was drawn on. Optional. Stored as given and copied onto every booking this order funds; holds and the booking routes never take one of their own. A searchId MarketBox never issued is kept but not counted.

Example:
reservationId
string

The hold this order funds. Preferred: the hold already knows where the booking happens, so the order and its bookings cannot disagree on price.

Minimum string length: 1
Example:

"resv_01kx16f0a1c7b2sd91xzq3mn5p"

locationId
string

Stored Location for a PHYSICAL booking. Ignored when reservationId is given.

Minimum string length: 1
address
object

Service address for a TRAVEL_ZONE (in-home) booking. Ignored when reservationId or locationId is given.

items
object[]

Line items to purchase.

Response

Order created

data
object
required