Orders

Update an order

Update mutable fields on an existing order. Used for in-progress edits — attaching or swapping a customer, recording contact details against the order, advancing the basket stage, and so on.

customer_id is interpreted specially. Passing a string ID attaches that customer to the order (subject to availability and brand checks); passing null removes the current customer.

If stage is the only field supplied, the order takes a fast path that just records the new stage and returns — useful for keeping live dashboards in sync without re-running the full update pipeline.

metadata uses merge semantics: existing keys not mentioned in the request stay in place, keys passed with a value are upserted, and keys passed with null are removed.

special_requests is writable only by users that hold the SETTINGS_MANAGE permission; for everyone else the field is silently dropped before validation.

put/shop/orders/{orderId}

Request body

customer_idstring nullable

Attach or detach a customer. Pass a customer ID to set the order's customer; pass null to remove the current customer. The customer must belong to the same brand as the order's site.

sales_channel_idstring nullable

The sales channel to attribute the order to.

first_namestring

First name to record against the order. When set, this also copies through to the lead-booker guest (if one exists) so the order header and the lead guest stay in sync.

last_namestring

Last name to record against the order.

emailstring email

Email address to record against the order. Must be a syntactically valid address.

phonestring nullable

International phone number for the order. Validated and normalised against the site's country code; stored in E.164 format.

integration_config_idstring nullable

Optional reference to an IntegrationConfig that scopes this order to a specific integration on the site (for example a PMS connector). Must reference a config that belongs to the same site.

stagestring

The current basket/order stage. Stages model the user-facing checkout flow (e.g. customer_details, payment, confirmation) and are surfaced to operators. When the only field supplied is stage, the order is updated as a lightweight stage transition without running the full update pipeline.

external_refstring

Free-form reference from the calling system. Stored verbatim on the order.

metadataobject

Arbitrary string-to-string metadata to merge into the order. Keys map to string values up to 1,000 characters; passing null for a value removes that key. Existing metadata not mentioned in the request is left in place (merge semantics, not replace).

special_requestsstring nullable

Operator-facing notes captured against the order. Only writable by users with the SETTINGS_MANAGE permission; omitted from the request body for everyone else.

Example request

{
  "customer_id": "5f1a83b9d52d5c2c8b8b4567",
  "sales_channel_id": "5f1a83b9d52d5c2c8b8b4569",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "phone": "+447700900123",
  "integration_config_id": "5f1a83b9d52d5c2c8b8b4571",
  "stage": "payment",
  "external_ref": "PMS-12345",
  "special_requests": "Quiet room requested."
}

Response

The Order was successfully retrieved

Changes

No recorded changes to this endpoint across all 1 revision of this API.