Update Order
Update a native agentic order. Supports external order identifiers, status, currency, country, totalAmount, shippingFee, discountAmount, metadata, orderCreatedAt, and line-item upserts (externalOrderItemId, price / unitPrice / paidPrice / costPrice / currency / status / quantity). Matching externalOrderItemId updates a line; a new externalOrderItemId with productName + quantity inserts a line (multi-SKU append). When totalAmount is omitted and lines change, the order total is recomputed from all lines. When country is omitted and stored country is empty, Omni derives country from the resulting order currency when unambiguous. Requires orders:write. Marketplace orders (Shopee, Lazada, TikTok, Shopify) are rejected with HTTP 409 — those fields are marketplace-owned. Emits order.status.changed when status changes and order.updated for other field changes.
Authorizations
Bearer API key for server-to-server access. Session auth is also supported in first-party UI flows.
Path Parameters
OmniCommerce order UUID returned from create or list.
Body
At least one of externalOrderId, externalOrderNumber, status, currency, country, totalAmount, shippingFee, discountAmount, metadata, orderCreatedAt, or items is required.
Optional for OAuth clients bound to one organization; required when the caller can access multiple organizations.
120Replacement stable external order identifier. Must be unique among agentic orders in the organization.
160Replacement customer-facing external order number.
160Canonical order status: pending, to_ship, shipped, completed, return, canceled.
pending, to_ship, shipped, completed, return, canceled ISO-4217 currency code for the order. When country is empty, unambiguous market currencies also derive country (see country field).
3Marketplace country (code or name). Optional. When omitted and the order's stored country is empty, Omni derives from the resulting order currency when unambiguous (SGD→singapore, MYR→malaysia, PHP→philippines, HKD→hong kong, etc.). Explicit country always wins. USD is not used to derive country.
80Order total. When omitted and line prices change, recomputed from line paid/unit prices × quantity.
x >= 0x >= 0x >= 0Optional shallow merge into existing order metadata (does not replace the full object).
Replacement order created timestamp (ISO 8601 with timezone). Overwrites stored order_created_at used by listing and analytics date filters. Omitted value is left unchanged. Re-posting POST /api/v1/orders with the same externalOrderId does not overwrite an existing created date.
Line upserts. Match by externalOrderItemId or productId to update. To replace a line identifier, select with currentExternalOrderItemId and provide the new externalOrderItemId. To append a multi-SKU line, send a new externalOrderItemId with productName and quantity.
1 - 100 elementsResponse
Order updated (or unchanged no-op).
The response is of type object.