Orders API

Use the Developer Platform orders endpoints to list workspace orders with the same filters as the UI, create native agentic orders from external systems, and patch agentic order fields (status, created date, money, currency, and line items). Settlements (fees, settlement status, marketplace net, and payment received) are not order fields. Use the Settlements API (POST /api/v1/settlements).

Authentication

Send an OmniCommerce API key or OAuth client-credentials token:

Authorization: Bearer $OMNI_API_KEY
Content-Type: application/json

Endpoint	Required scope
`GET /api/v1/orders`	`orders:read`
`POST /api/v1/orders`	`orders:write`
`PATCH /api/v1/orders/{orderId}`	`orders:write`

OAuth clients must include the scope on the client. API keys created from organization settings receive all developer scopes by default. Session-authenticated calls must include organizationId in the query (GET) or JSON body (POST/PATCH).

Order status enum

Canonical statuses for create and patch (also used as listing filter groups):

Status	Meaning
`pending`	Unpaid / not ready to fulfill
`to_ship`	Paid / ready for seller fulfillment
`shipped`	In transit / handed to carrier
`completed`	Delivered / finished
`return`	Return or refund in progress / done
`canceled`	Canceled or invalid

Marketplace-imported orders may store platform-specific raw status strings; the developer write APIs only accept this enum.

Pricing fields

Money fields on orders and line items:

Field	Level	Meaning
`currency`	Order and/or line	ISO-4217 code (for example `SGD`, `MYR`, `PHP`, `HKD`).
`country`	Order	Marketplace country. When empty, derived from order currency when unambiguous (see below).
`totalAmount`	Order	Order total. On create, computed from line paid/unit prices × quantity when omitted.
`shippingFee`	Order	Shipping fee.
`discountAmount`	Order	Order-level discount.
`price`	Line	Alias for `unitPrice` (list / original unit price). Prefer `unitPrice` on new integrations.
`unitPrice`	Line	Per-unit list / sticker price before line discounts.
`paidPrice`	Line	Per-unit amount actually charged after discounts (preferred for GMV and totals).
`costPrice`	Line	Unit COGS (not a selling price). See below.
`costPriceCurrency` / `costCurrency`	Line	Currency of the raw `costPrice` (e.g. `USD`).
`costPriceFxRate`	Line	Manual FX: units of target per 1 unit of cost currency.
`costPriceFxTo`	Line	Target currency (defaults to line/order currency).
`costPriceFxAsOf`	Line	`YYYY-MM` or `YYYY-MM-DD` for Frankfurter auto-rate.

`price` vs `unitPrice` vs `paidPrice`

These three are selling prices on the line (per unit). They are not COGS and not marketplace fees.

Field	Meaning	When to send
`unitPrice`	List / original unit price (before line discount)	Optional; useful for “was / now” or discount reporting
`price`	Same as `unitPrice` (legacy alias)	Optional; prefer `unitPrice` for new code
`paidPrice`	What the buyer paid per unit after discounts	Preferred for totals, GMV, and return refund estimates

How Omni picks a number for line money

If paidPrice is set → use paidPrice × quantity
Else if unitPrice or price is set → use that × quantity
Else if productId is set on create → may resolve from the product catalog

You do not need all three. For most agentic / Zalora-style integrations, send one selling price:

{ "quantity": 1, "paidPrice": 80 }

or, if you only have a single price field in your system:

{ "quantity": 1, "price": 80 }

Use both list and paid when they differ:

{
  "quantity": 1,
  "unitPrice": 100,
  "paidPrice": 80
}

Do not confuse with
`totalAmount`	Order-level total (all lines + fees you pass)
`costPrice`	Unit COGS (cost of goods), not revenue

These field descriptions are also published on OpenAPI / Redocly (POST/PATCH /api/v1/orders line schemas).

`costPrice` (product-owned)

costPrice is not a first-class order table column. Its reusable catalog value is stored at: products.product_data.costPrice When you send items[].costPrice with a productId:

OmniCommerce upserts product_data.costPrice and product_data.costPriceCurrency on that product (after FX, in local/target currency).
The value is snapshotted on the order line as metadata.costPrice; this snapshot is canonical for historical order/P&L economics.

Rules:

costPrice belongs on the items[] array (per line), not on the order root.
Omitted costPrice never clears an existing product or line cost.
When omitted on create with productId, the line snapshot may still resolve from the product catalog if a cost is already stored there.
Product cost is only written when costPrice is explicitly present on the request.

Cost currency and FX

P&L treats costPrice as the same unit as order revenue. When invoice COGS is in another currency (e.g. USD) and the order is MYR/SGD/PHP/HKD:

{
  "costPrice": 120,
  "costPriceCurrency": "USD",
  "costPriceFxTo": "MYR",
  "costPriceFxRate": 4.45,
  "costPriceFxAsOf": "2026-07"
}

Rate meaning: 1 USD = 4.45 MYR → stored local cost 534.
If costPriceCurrency differs from the target and costPriceFxRate is omitted, Omni fetches the rate from Frankfurter (getFxQuote / ECB daily rates). Optional costPriceFxAsOf pins a historical date (YYYY-MM-DD or month YYYY-MM).
Line metadata keeps an audit trail: sourceCostPrice, sourceCostCurrency, costPriceFxRate, costPriceFxFrom, costPriceFxTo, costPriceFxAsOf, costPriceFxSource (manual | frankfurter | fallback | identity).
Alias: costCurrency = costPriceCurrency.
Manual seller rates always win over auto FX.
costPriceFxTo must match the effective line/order currency so COGS and revenue remain comparable.
Cost currency and FX fields require an explicit costPrice on the same line. A currency-tagged catalog fallback is converted when its stored currency differs from the new line/order currency.
When no rate can be resolved (unsupported pair, FX provider unreachable), the request fails with 400 before the order is written — retry with costPriceFxRate.

Catalog fallbacks on create

When line price / unitPrice / paidPrice / currency are omitted and productId is provided, create resolves missing values from the product catalog (products.price, product_data, currency). Order total is then computed from the resolved line amounts when totalAmount is omitted.

List orders

GET /api/v1/orders

Query parameters

These match the workspace Orders listing page (/app/{organizationId}/orders):

Parameter	Description
`organizationId`	Organization scope for session auth. Optional for single-org OAuth/API keys.
`q`	Search order number, external order ID, buyer fields, and line-item product/SKU fields.
`status`	Status group filter: `to_ship`, `shipped`, `completed`, `pending`, `return`, `canceled`.
`marketplace`	Comma-separated platforms, for example `shopee,lazada,tiktok`.
`country`	Comma-separated normalized country codes.
`store`	Comma-separated marketplace account IDs.
`sortBy`	Comma-separated sort tokens (multi-sort, max 6). Default: `created_desc`. Aliases: `latest` → `created_desc`, `oldest` → `created_asc`.
`dateFrom`	Inclusive created-date lower bound (`YYYY-MM-DD`).
`dateTo`	Inclusive created-date upper bound (`YYYY-MM-DD`).
`offset`	Zero-based pagination offset. Default `0`.
`limit`	Page size. Default `20`, max `50`.

Response

Each item includes order totals and line money fields when available:

{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "externalOrderId": "partner-order-1001",
      "status": "pending",
      "statusGroup": "pending",
      "marketplace": "agentic",
      "currency": "SGD",
      "totalAmount": 100,
      "totalLabel": "SGD 100.00",
      "totalQuantity": 2,
      "lines": [
        {
          "id": "line_1",
          "name": "Linen Wrap Dress",
          "quantity": 2,
          "sku": "DRESS-001",
          "productId": "11111111-1111-4111-8111-111111111111",
          "unitPrice": 50,
          "paidPrice": 50,
          "costPrice": 20,
          "currency": "SGD"
        }
      ]
    }
  ],
  "hasMore": false,
  "nextOffset": 20,
  "summary": {
    "totalCount": 1,
    "toShipCount": 0,
    "shippedCount": 0,
    "completedCount": 0,
    "pendingCount": 1,
    "returnCount": 0,
    "canceledCount": 0
  },
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 1,
    "hasMore": false,
    "nextOffset": null,
    "maxLimit": 50,
    "defaultLimit": 20
  }
}

Line costPrice is read from the order-line metadata snapshot (metadata.costPrice).

Create order

POST /api/v1/orders

Creates a native agentic order and line items through the same upsert path used by agentic checkout completion. Marketplace orders should continue to flow through marketplace import/webhook pipelines.

Request body

{
  "organizationId": "org_123",
  "externalOrderId": "partner-order-1001",
  "externalOrderNumber": "PO-1001",
  "status": "to_ship",
  "currency": "SGD",
  "totalAmount": 100,
  "shippingFee": 5,
  "discountAmount": 0,
  "country": "SG",
  "buyer": {
    "name": "Alex Buyer",
    "email": "[email protected]",
    "phone": "+6590000000"
  },
  "shippingAddress": {
    "line1": "123 Market Street",
    "city": "Singapore",
    "country": "SG"
  },
  "items": [
    {
      "productId": "11111111-1111-4111-8111-111111111111",
      "productName": "Linen Wrap Dress",
      "sku": "DRESS-001",
      "quantity": 2,
      "price": 50,
      "unitPrice": 50,
      "paidPrice": 50,
      "costPrice": 20,
      "currency": "SGD",
      "status": "to_ship"
    }
  ],
  "metadata": {
    "sourceSystem": "partner-erp"
  }
}

Field	Required	Notes
`items`	Yes	At least one line item (max 100).
`items[].productName`	Yes	Display name for the line.
`items[].quantity`	Yes	Positive integer.
`items[].externalOrderItemId`	No	Stable line id for upserts and recon. Prefer partner per-SKU row id or marketplace item id. Generated as `{externalOrderId}-{index}` when omitted.
`items[].productId`	No	Product UUID. Enables catalog fallbacks and product `costPrice` upsert.
`items[].price`	No	Alias for `unitPrice`.
`items[].unitPrice`	No	Per-unit list price. Falls back to product catalog when omitted with `productId`.
`items[].paidPrice`	No	Per-unit paid price; preferred for totals when set.
`items[].costPrice`	No	Unit COGS. With `productId`, upserts product `product_data.costPrice`. Omitted value never clears existing cost.
`items[].sku` / `sellerSku`	No	SKU fields. `sellerSku` is used as a secondary Zalora recon match when unique on the order.
`items[].currency`	No	Line currency; falls back to order then product.
`items[].status`	No	Line status (canonical enum). Defaults to order status.
`status`	No	Canonical enum (default `pending`).
`currency`	No	Order currency (ISO-4217). Prefer market currency for marketplace recon (e.g. PHP for Zalora PH, not catalog SGD).
`country`	No	Marketplace country (`SG`, `singapore`, `PH`, `philippines`, …). When omitted/empty, Omni derives from order currency when unambiguous (see Country from currency). Shipping address `country` is used when top-level `country` is omitted.
`externalOrderId`	No	Stable upsert key (unique per org + agentic). For marketplace recon use the marketplace order number. Generated when omitted.
`externalOrderNumber`	No	Customer-facing number; defaults to `externalOrderId`.
`platform`	No	Always `agentic` for this endpoint.
`totalAmount`	No	When omitted, recomputed from all lines after upsert (safe for sequential multi-SKU posts). When set, stored as provided.
`shippingFee`	No	Shipping fee.
`discountAmount`	No	Order-level discount.
`orderCreatedAt`	No	ISO 8601 datetime with timezone. Stored as `order_created_at` (listing and analytics date filters). Defaults to now. Re-posting the same `externalOrderId` does not overwrite an existing created date — use PATCH.

Re-posting the same platform + externalOrderId pair updates the existing order and returns HTTP 200 with created: false. Lines upsert by externalOrderItemId.

Country from currency

When order country is empty, Omni may set country from order currency (and the same rule applies on PATCH and Zalora recon apply). Explicit country always wins.

Currency	Derived country (stored canonical name)
`SGD`	`singapore`
`MYR`	`malaysia`
`PHP`	`philippines`
`HKD`	`hong kong`
`THB`	`thailand`
`VND`	`vietnam`
`IDR`	`indonesia`
`TWD`	`taiwan`
`BRL`	`brazil`
`USD`	(not derived — ambiguous)

Workspace order listing and detail use the same fallback for display when stored country is empty.

Multi-SKU / one-row-per-SKU partners (Zalora recon)

Omni models one marketplace order → one Omni order. Marketplace recon (for example Zalora Item Transaction Reports) matches the report order number to agentic external_order_id, then matches lines by external_order_item_id or unique Seller SKU on that order. If your system stores one row per SKU that share a marketplace order id:

Always use the marketplace order id as externalOrderId (not your per-SKU order number).
Put your unique per-SKU id on items[].externalOrderItemId.
You may POST one line at a time with the same externalOrderId — lines upsert onto the same Omni order.
Omit totalAmount when appending lines so Omni recomputes the order total from all lines. Send totalAmount only when you know the full cart total.

Do not invent composite externalOrderId values like MP-12345:SKU-A for uniqueness — recon will not match the marketplace order number. If you already created separate Omni orders per SKU with different external ids, create/upsert again using the marketplace order id as externalOrderId and stable line externalOrderItemIds (preferred going forward). Do not set the same marketplace id on multiple Omni order shells via PATCH — that still returns 409.

Example: Zalora cart with 2 SKUs

Your system (one DB row per SKU):

Your order #	Marketplace order id	SKU	Paid
`ORD-9001`	`3012345678`	`SKU-A`	50 SGD
`ORD-9002`	`3012345678`	`SKU-B`	40 SGD

Wrong — two Omni orders (or same externalOrderId on two shells → 409):

POST /api/v1/orders
Authorization: Bearer $OMNI_API_KEY
Content-Type: application/json

{
  "externalOrderId": "ORD-9001",
  "currency": "SGD",
  "items": [
    {
      "externalOrderItemId": "ORD-9001",
      "sku": "SKU-A",
      "productName": "Item A",
      "quantity": 1,
      "paidPrice": 50
    }
  ]
}

POST /api/v1/orders
Authorization: Bearer $OMNI_API_KEY
Content-Type: application/json

{
  "externalOrderId": "ORD-9002",
  "currency": "SGD",
  "items": [
    {
      "externalOrderItemId": "ORD-9002",
      "sku": "SKU-B",
      "productName": "Item B",
      "quantity": 1,
      "paidPrice": 40
    }
  ]
}

Zalora report order 3012345678 will not match either shell. Right — one Omni order; your row ids become line ids. Same marketplace id on every push; omit totalAmount so Omni sums all lines:

POST /api/v1/orders
Authorization: Bearer $OMNI_API_KEY
Content-Type: application/json

{
  "externalOrderId": "3012345678",
  "externalOrderNumber": "3012345678",
  "currency": "SGD",
  "status": "to_ship",
  "items": [
    {
      "externalOrderItemId": "ORD-9001",
      "sku": "SKU-A",
      "sellerSku": "SKU-A",
      "productName": "Item A",
      "quantity": 1,
      "paidPrice": 50
    }
  ]
}

First response (201, created: true):

{
  "ok": true,
  "status": "completed",
  "data": {
    "orderId": "11111111-1111-4111-8111-111111111111",
    "externalOrderId": "3012345678",
    "created": true,
    "platform": "agentic",
    "totalAmount": 50
  }
}

POST /api/v1/orders
Authorization: Bearer $OMNI_API_KEY
Content-Type: application/json

{
  "externalOrderId": "3012345678",
  "externalOrderNumber": "3012345678",
  "currency": "SGD",
  "status": "to_ship",
  "items": [
    {
      "externalOrderItemId": "ORD-9002",
      "sku": "SKU-B",
      "sellerSku": "SKU-B",
      "productName": "Item B",
      "quantity": 1,
      "paidPrice": 40
    }
  ]
}

Second response (200, created: false — same order, second line appended):

{
  "ok": true,
  "status": "completed",
  "data": {
    "orderId": "11111111-1111-4111-8111-111111111111",
    "externalOrderId": "3012345678",
    "created": false,
    "platform": "agentic",
    "totalAmount": 90
  }
}

Result in Omni:

Field	Value
One order `externalOrderId`	`3012345678` (matches Zalora order number)
Line 1 `externalOrderItemId`	`ORD-9001` (your unique row)
Line 2 `externalOrderItemId`	`ORD-9002`
`totalAmount`	`90` (recomputed from both lines)

You can also send both lines in one request if your push job can group by marketplace order id:

POST /api/v1/orders
Authorization: Bearer $OMNI_API_KEY
Content-Type: application/json

{
  "externalOrderId": "3012345678",
  "externalOrderNumber": "3012345678",
  "currency": "SGD",
  "status": "to_ship",
  "items": [
    {
      "externalOrderItemId": "ORD-9001",
      "sku": "SKU-A",
      "sellerSku": "SKU-A",
      "productName": "Item A",
      "quantity": 1,
      "paidPrice": 50
    },
    {
      "externalOrderItemId": "ORD-9002",
      "sku": "SKU-B",
      "sellerSku": "SKU-B",
      "productName": "Item B",
      "quantity": 1,
      "paidPrice": 40
    }
  ]
}

Response

{
  "ok": true,
  "apiVersion": "developer_v1",
  "operationId": "8f7e8f8f-2b9e-46e6-a2c0-50d0f4612b2d",
  "status": "completed",
  "warnings": [],
  "recommendations": [],
  "links": {
    "order": "/api/v1/orders?organizationId=org_123&q=partner-order-1001"
  },
  "data": {
    "orderId": "00000000-0000-4000-8000-000000000001",
    "externalOrderId": "partner-order-1001",
    "created": true,
    "platform": "agentic",
    "totalAmount": 100
  }
}

Response field	Notes
`orderId`	OmniCommerce order UUID. Stable across re-posts of the same `externalOrderId`.
`externalOrderId`	Echo of the upsert key.
`created`	`true` on first insert (`201`); `false` on upsert (`200`).
`platform`	Always `agentic` for this endpoint.
`totalAmount`	Final order total after create/upsert (explicit request value, or recomputed from all lines when omitted).

Update order

PATCH /api/v1/orders/{orderId}

Updates a native agentic order. Supports external order identifiers, status, created date, currency, country, money fields, metadata, and line-item upserts (externalOrderItemId, price / unitPrice / paidPrice / costPrice / currency / status / quantity, and more). Marketplace orders are rejected with 409 — those fields are marketplace-owned. Use marketplace tooling or the workspace order-actions flow for them. At least one of externalOrderId, externalOrderNumber, status, currency, country, totalAmount, shippingFee, discountAmount, metadata, orderCreatedAt, or items is required. When country is omitted and the order’s stored country is empty, Omni fills country from the resulting order currency (same map as create — see Country from currency). Line upserts: matching externalOrderItemId (or unique productId) updates the line. A new externalOrderItemId with productName + quantity inserts a line (multi-SKU append on an existing order). When totalAmount is omitted and lines change, Omni recomputes the total from all lines.

Path parameters

Parameter	Description
`orderId`	OmniCommerce order UUID from create or list.

Request body

Status-only:

{
  "organizationId": "org_123",
  "status": "shipped",
  "metadata": {
    "trackingNumber": "SG123456789",
    "carrier": "Ninja Van"
  }
}

Money, currency, and line pricing (status optional):

{
  "organizationId": "org_123",
  "currency": "SGD",
  "totalAmount": 120.5,
  "shippingFee": 5,
  "items": [
    {
      "externalOrderItemId": "partner-order-1001-1",
      "price": 110,
      "costPrice": 45,
      "currency": "SGD"
    }
  ]
}

Correct created date:

{
  "organizationId": "org_123",
  "orderCreatedAt": "2026-03-15T08:00:00.000Z"
}

Repair identifiers on an imported order:

{
  "organizationId": "org_123",
  "externalOrderId": "MY-223347629SG",
  "externalOrderNumber": "MY-223347629SG",
  "items": [
    {
      "currentExternalOrderItemId": "dev-order-1",
      "externalOrderItemId": "10817558"
    }
  ]
}

Field	Required	Notes
(at least one mutable field)	Yes	Empty body is rejected.
`externalOrderId`	No	Replacement stable order identifier. Must be unique among agentic orders in the organization.
`externalOrderNumber`	No	Replacement customer-facing order number.
`status`	No	Canonical enum. Optional when patching money/lines/metadata.
`currency`	No	Order currency (ISO-4217).
`country`	No	Marketplace country. When omitted and stored country is empty, derived from order currency when unambiguous. Explicit value always wins.
`totalAmount`	No	Order total. When omitted and line prices change, recomputed from lines.
`shippingFee`	No	Shipping fee.
`discountAmount`	No	Order-level discount.
`orderCreatedAt`	No	ISO 8601 datetime with timezone. Overwrites stored `order_created_at`. Omitted value is left unchanged.
`organizationId`	Session multi-org only	Optional for single-org API keys / OAuth clients.
`metadata`	No	Shallow merge into existing order metadata (does not replace the whole object).
`items`	No	Partial line updates (1–100).

Line patch identity

Each items[] entry must identify a line with:

Field	Notes
`currentExternalOrderItemId`	Current line identifier. Use this selector when replacing `externalOrderItemId`.
`externalOrderItemId`	Selects the current line when `currentExternalOrderItemId` is omitted. When both are present, this is the replacement identifier. If no line matches and `productName` + `quantity` are set, a new line is inserted.
`productId`	Allowed when that product appears on exactly one line of the order.

Each patch line must also include at least one field to update (price, unitPrice, paidPrice, costPrice, currency, status, quantity, etc.), or productName + quantity when inserting a new line. Omitted costPrice on a line patch does not clear product or line cost. Explicit costPrice with a resolved product id upserts the product catalog cost.

Partial vs full return (line status)

Canonical line/order status return marks a return. Returns are line-level; order status is a roll-up. Partial return — one of several lines returned (order stays sold for remaining lines):

PATCH /api/v1/orders/{orderId}
Authorization: Bearer $OMNI_API_KEY
Content-Type: application/json

{
  "items": [
    {
      "externalOrderItemId": "ORD-9001",
      "status": "return"
    }
  ]
}

Response includes roll-up fields:

Field	Partial example
`returnState`	`partial`
`hasReturnSignal`	`true`
`returnRefundAmount`	≥ revenue of returned line(s) (`paidPrice × qty`)
`includeInSalesMetrics`	`true` (kept lines still count)
`status` / `statusGroup`	Unchanged unless you set top-level `status`

P&L and product economics treat returned lines as sold qty 0. Ledger fees with external_order_item_id attribute to that line; remaining fees pro-rate by sold line revenue. Full return — every line returned (or set order status explicitly):

{
  "items": [
    { "externalOrderItemId": "ORD-9001", "status": "return" },
    { "externalOrderItemId": "ORD-9002", "status": "return" }
  ]
}

When all lines are return and you did not send a different top-level status, Omni sets order status to return, returnState to full, and returnRefundAmount to at least the full order total so retained revenue is zero. You can still force full-order return with:

{ "status": "return" }

That top-level status marks every line return, zeros line paymentReceived, rolls up refund/sales flags, and restocks product inventory only when the line had inventory deducted on sale (metadata.inventoryDeductedAt). Line selection by productId works the same as by externalOrderItemId (must be unique on the order). PATCH responses and each GET /api/v1/orders item surface unit-economics fields:

Field	Meaning
`paymentReceived`	Sum of non-returned line payment-received; null until every active line is reconciled
`orderCogs`	Sum of sold line `metadata.costPrice × qty`; null while any active line lacks COGS
`orderProfit`	`paymentReceived − orderCogs`; null if either input is incomplete
`orderMargin`	`orderProfit / paymentReceived` (null if no payment)

Optional per-line refund override: set items[].metadata.returnRefundAmount before/with the status patch; roll-up prefers that over paidPrice × qty.

Example: append a second SKU via PATCH

After creating order 3012345678 with line ORD-9001, append line ORD-9002 without re-posting the whole cart:

PATCH /api/v1/orders/11111111-1111-4111-8111-111111111111
Authorization: Bearer $OMNI_API_KEY
Content-Type: application/json

{
  "items": [
    {
      "externalOrderItemId": "ORD-9002",
      "productName": "Item B",
      "sku": "SKU-B",
      "sellerSku": "SKU-B",
      "quantity": 1,
      "paidPrice": 40,
      "currency": "SGD"
    }
  ]
}

Response includes recomputed totalAmount (e.g. 90 when the first line was 50). Omit top-level totalAmount so Omni sums all lines. Update an existing line (same id) by sending only the fields to change:

PATCH /api/v1/orders/11111111-1111-4111-8111-111111111111
Authorization: Bearer $OMNI_API_KEY
Content-Type: application/json

{
  "items": [
    {
      "externalOrderItemId": "ORD-9002",
      "paidPrice": 38,
      "quantity": 2
    }
  ]
}

Response

{
  "ok": true,
  "apiVersion": "developer_v1",
  "operationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "warnings": [],
  "recommendations": [],
  "links": {
    "order": "/api/v1/orders?organizationId=org_123&q=partner-order-1001"
  },
  "data": {
    "orderId": "00000000-0000-4000-8000-000000000001",
    "externalOrderId": "partner-order-1001",
    "externalOrderNumber": "PO-1001",
    "platform": "agentic",
    "previousStatus": "to_ship",
    "status": "shipped",
    "statusGroup": "shipped",
    "currency": "SGD",
    "totalAmount": 120.5,
    "shippingFee": 5,
    "discountAmount": 0,
    "orderCreatedAt": "2026-03-15T08:00:00.000Z",
    "changed": true,
    "changedFields": [
      "status",
      "currency",
      "totalAmount",
      "items.unitPrice",
      "items.costPrice"
    ]
  }
}

changed is false when the request is a no-op. changedFields lists what actually changed.

Errors

400 — invalid JSON, validation failure, unknown status, missing patch fields, or line identity failure.
401 — missing or invalid bearer token / session.
403 — missing orders:read or orders:write scope.
404 — order not found for this organization (PATCH only).
409 — updates not supported for marketplace-owned orders, or an external identifier is already in use.
429 — developer API rate limit exceeded.
500 — unexpected server failure.

Developer Platform
OpenAPI reference
Authentication
Agentic checkout endpoints: POST /api/v1/checkout-sessions in the API reference

Get started

Guides

MCP

Authentication

Order status enum

Pricing fields

`price` vs `unitPrice` vs `paidPrice`

`costPrice` (product-owned)

Cost currency and FX

Catalog fallbacks on create

List orders

Query parameters

Response

Create order

Request body

Country from currency

Multi-SKU / one-row-per-SKU partners (Zalora recon)

Example: Zalora cart with 2 SKUs

Response

Update order

Path parameters

Request body

Line patch identity

Partial vs full return (line status)

Example: append a second SKU via PATCH

Response

Errors

​Authentication

​Order status enum

​Pricing fields

​price vs unitPrice vs paidPrice

​costPrice (product-owned)

​Cost currency and FX

​Catalog fallbacks on create

​List orders

​Query parameters

​Response

​Create order

​Request body

​Country from currency

​Multi-SKU / one-row-per-SKU partners (Zalora recon)

​Example: Zalora cart with 2 SKUs

​Response

​Update order

​Path parameters

​Request body

​Line patch identity

​Partial vs full return (line status)

​Example: append a second SKU via PATCH

​Response

​Errors

​Related docs

Authentication

Order status enum

Pricing fields

`price` vs `unitPrice` vs `paidPrice`

`costPrice` (product-owned)

Cost currency and FX

Catalog fallbacks on create

List orders

Query parameters

Response

Create order

Request body

Country from currency

Multi-SKU / one-row-per-SKU partners (Zalora recon)

Example: Zalora cart with 2 SKUs

Response

Update order

Path parameters

Request body

Line patch identity

Partial vs full return (line status)

Example: append a second SKU via PATCH

Response

Errors

Related docs