curl --request PATCH \
--url https://omnicommerce.sg/api/v1/orders/{orderId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"organizationId": "org_123",
"externalOrderId": "MY-223347629SG",
"externalOrderNumber": "MY-223347629SG",
"status": "shipped",
"currency": "SGD",
"totalAmount": 120.5,
"items": [
{
"currentExternalOrderItemId": "dev-order-1",
"externalOrderItemId": "10817558",
"price": 110,
"costPrice": 45,
"currency": "SGD"
}
],
"metadata": {
"trackingNumber": "SG123456789"
}
}
'{}Update Order
Update a native agentic order.
Authentication
Requires orders:write.
Supported changes
- External order identifiers, status, currency, and country
totalAmount,shippingFee, anddiscountAmount- Metadata and
orderCreatedAt - Line identifiers, prices, COGS, currency, status, and quantity
Line upserts
- A matching
externalOrderItemIdupdates the existing line. - A new
externalOrderItemIdwithproductNameandquantityappends a line. - When lines change and
totalAmountis omitted, OmniCommerce recomputes the total from all lines.
Country resolution
When country is omitted and the stored country is empty, OmniCommerce may derive it from an unambiguous resulting order currency.
Restrictions and events
Marketplace-owned orders from Shopee, Lazada, TikTok, and Shopify are rejected with 409 Conflict. A status change emits order.status.changed; other changes emit order.updated.
curl --request PATCH \
--url https://omnicommerce.sg/api/v1/orders/{orderId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"organizationId": "org_123",
"externalOrderId": "MY-223347629SG",
"externalOrderNumber": "MY-223347629SG",
"status": "shipped",
"currency": "SGD",
"totalAmount": 120.5,
"items": [
{
"currentExternalOrderItemId": "dev-order-1",
"externalOrderItemId": "10817558",
"price": 110,
"costPrice": 45,
"currency": "SGD"
}
],
"metadata": {
"trackingNumber": "SG123456789"
}
}
'{}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 elementsShow child attributes
Show child attributes
Response
Order updated (or unchanged no-op).
The response is of type object.