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"
}
]
}
'{}{}Create Order
Create a native agentic order with line items. This operation uses the same upsert path as agentic checkout completion.
Authentication
Requires orders:write.
Upsert behavior
- Reusing an
externalOrderIdupdates the existing order instead of creating a duplicate. - For one-row-per-SKU integrations, use the marketplace order ID as
externalOrderIdand the row ID asitems[].externalOrderItemId. - When
totalAmountis omitted, OmniCommerce recomputes it from all order lines after the upsert.
Pricing and catalog defaults
- Each line can provide
price,unitPrice,paidPrice, andcostPrice. - When
productIdis provided, missing price or currency values may resolve from the product catalog. - An explicit
costPriceupdatesproduct_data.costPriceand is snapshotted on the order line. Omitting it never clears an existing product cost.
Country resolution
When country is empty, OmniCommerce may derive it from an unambiguous order currency, such as PHP for the Philippines. USD is not used to infer a country.
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
Bearer API key for server-to-server access. Session auth is also supported in first-party UI flows.
Body
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.
1 - 100 elementsShow child attributes
Show child attributes
Optional for OAuth clients bound to one organization; required when the caller can access multiple organizations.
120Stable 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.
160Customer-facing order number. Defaults to externalOrderId when omitted.
160agentic Canonical order status. Same enum as PATCH /api/v1/orders/{orderId}.
pending, to_ship, shipped, completed, return, canceled 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.
3Order 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.
x >= 0x >= 0x >= 0Marketplace 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.
80160Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
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.
Response
Existing order updated for the same platform/externalOrderId pair.
The response is of type object.