curl --request POST \
  --url https://omnicommerce.sg/api/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "productId": "11111111-1111-4111-8111-111111111111",
      "productName": "Linen Wrap Dress",
      "sku": "DRESS-001",
      "quantity": 1,
      "price": 49.99,
      "unitPrice": 49.99,
      "paidPrice": 49.99,
      "costPrice": 20,
      "currency": "USD"
    }
  ]
}
'

{}

{}

Orders

Create Order

Create a native agentic order with line items. Supports status, currency, country, totalAmount, and per-line price / unitPrice / paidPrice / costPrice. When productId is provided, missing price/currency may resolve from the product catalog; explicit costPrice upserts product_data.costPrice and is snapshotted on the line. Omitted costPrice never clears existing product cost. When country is empty, Omni may derive marketplace country from order currency (e.g. PHP→philippines; USD is not guessed). Reuses the same upsert path as agentic checkout completion. Requires orders:write. Re-posting the same externalOrderId updates the existing order instead of creating a duplicate — partners who store one row per SKU should reuse the marketplace order id as externalOrderId and put their unique row id on items[].externalOrderItemId. When totalAmount is omitted, the order total is recomputed from all lines after upsert.

POST

api

orders

curl --request POST \
  --url https://omnicommerce.sg/api/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "productId": "11111111-1111-4111-8111-111111111111",
      "productName": "Linen Wrap Dress",
      "sku": "DRESS-001",
      "quantity": 1,
      "price": 49.99,
      "unitPrice": 49.99,
      "paidPrice": 49.99,
      "costPrice": 20,
      "currency": "USD"
    }
  ]
}
'

{}

{}

Authorizations

Authorization

string

header

required

Bearer API key for server-to-server access. Session auth is also supported in first-party UI flows.

Body

application/json

items

object[]

required

Order lines. Partners with one row per SKU can send one item per request or all items in one request; reuse the same externalOrderId and distinct externalOrderItemId values.

Required array length: 1 - 100 elements

Show child attributes

organizationId

string

Optional for OAuth clients bound to one organization; required when the caller can access multiple organizations.

Maximum string length: 120

externalOrderId

string

Stable external order identifier and upsert key (unique per org + agentic platform). For marketplace recon (e.g. Zalora), use the marketplace order number — not a partner per-SKU row id. When omitted, OmniCommerce generates a developer order ID. Re-posting the same value upserts the same order and appends/updates lines by externalOrderItemId.

Maximum string length: 160

externalOrderNumber

string

Customer-facing order number. Defaults to externalOrderId when omitted.

Maximum string length: 160

platform

enum<string>

default:agentic

Available options:

agentic

status

enum<string>

default:pending

Canonical order status. Same enum as PATCH /api/v1/orders/{orderId}.

Available options:

pending,

to_ship,

shipped,

completed,

return,

canceled

currency

string

ISO-4217 order currency. Prefer marketplace market currency for recon (e.g. PHP for Zalora PH). When country is empty, unambiguous market currencies also derive country (SGD→singapore, MYR→malaysia, PHP→philippines, HKD→hong kong, etc.). USD is not used to derive country.

Required string length: 3

totalAmount

number

Order total. When omitted, Omni recomputes from all line paid/unit prices × quantity after item upsert (safe for sequential one-line-at-a-time multi-SKU pushes). When provided, the explicit value is stored as-is.

Required range: x >= 0

shippingFee

number

Required range: x >= 0

discountAmount

number

Required range: x >= 0

country

string

Marketplace country (code or name, e.g. SG, singapore, PH, philippines). Optional. When omitted or empty, Omni derives from order currency when unambiguous (SGD→singapore, MYR→malaysia, PHP→philippines, HKD→hong kong, THB→thailand, VND→vietnam, IDR→indonesia, TWD→taiwan, BRL→brazil). Explicit country always wins. Shipping address country is used when top-level country is omitted. Stored as a canonical full name when possible.

Maximum string length: 80

accountId

string

Maximum string length: 160

buyer

object

Show child attributes

shippingAddress

object

Show child attributes

billingAddress

object

Show child attributes

orderCreatedAt

string<date-time>

Order created timestamp (ISO 8601 with timezone). Defaults to now. Re-posting the same externalOrderId does not overwrite an existing created date; use PATCH /api/v1/orders/{orderId} to correct it.

orderUpdatedAt

string<date-time>

metadata

object

Response

Existing order updated for the same platform/externalOrderId pair.

The response is of type object.

Overview

Endpoints

Create Order

Authorizations

Body

Response