Orders
Preview an order
Runs everything POST /v1/orders does — pricing, offers, discount code, delivery and stock checks — and returns the order it WOULD create, with object: "order_preview" and no id. Nothing is saved, no stock moves and no number is used. Show this to a customer before they confirm.
Body
- customerobjectRequired
4 child fields
- namestringRequired
1–160 characters
- phonestringRequired
E.164 ("+213551234567") or the national form.
6–20 characters
- phone_2string or null
up to 20 characters
- emailstring or null
email · up to 160 characters
- shipping_addressobjectRequired
4 child fields
- countrystring
Optional. The store's own country is the only one accepted for now.
- regionstringRequired
A region from GET /v1/regions: its code ("16"), its ISO code ("DZ-16") or its name ("Alger", "الجزائر"; one typo is tolerated). The order stores the region code.
1–60 characters
- citystringRequired
The city's name. An unrecognised name sets
needs_review.1–160 characters
- address1stringRequired
1–500 characters
- deliveryobject
Required (with mode) when the store charges for delivery (GET /v1/delivery/rates says so). For a pickup or a cash collection, only courier_id is read.
4 child fields
- modestring
One of
home,pickup_point - courier_idstring
A courier from GET /v1/delivery/rates. Leave it out to use the cheapest rate for the mode.
starts with cour_
- pickup_point_idstring
up to 100 characters
- pickup_point_namestring
up to 200 characters
- line_itemsarray
What is delivered. Required except for a pickup (its goods are in collect) and a cash collection (it has none).
up to 100 items · at least 1 item
5 child fields
- variant_idstring
starts with var_
- titlestring
A custom line's name
1–240 characters
- variant_titlestring
up to 240 characters
- quantityintegerRequired
1–999
- unit_pricestring
Set the price by hand, as the dashboard's Create order allows. Leave it out to use the variant's price. Required on a custom line.
- typestring
delivery: goods go to the customer. exchange: goods go to the customer and the courier takes others back (collect). pickup: the courier only collects goods from the customer. cash_collection: no goods; the courier collects an amount (total).
One of
delivery,exchange,pickup,cash_collection
default "delivery" - collectobject
What the courier takes back, for an exchange or a pickup. Name lines of an earlier order with original_order_id and line_item_id (that order must be delivered), or describe them like line_items.
2 child fields
- original_order_idstring
starts with ord_
- linesarray of objectsRequired
up to 100 items · at least 1 item
6 child fields
- line_item_idstring
A line of original_order_id.
starts with li_
- variant_idstring
starts with var_
- titlestring
1–240 characters
- variant_titlestring
up to 240 characters
- quantityintegerRequired
1–999
- unit_pricestring
An amount as a decimal string in the store's currency, with no more decimals than the currency has ("3500.00" in DZD, "12.500" in TND).
- totalstring
What the courier collects, set by hand: the amount of a cash collection, the price difference of an exchange. Leave it out and it is the lines plus delivery.
- shipping_feestring
The delivery fee, set by hand instead of the store's rate.
- discount_codestring
1–20 characters
- offer_idsarray of strings
Offers the shopper took (a bundle, a quantity pack, a cross-sell add-on), as the storefront sends them. The store checks each one against the lines and its schedule, and applies only those that qualify; the rest are ignored.
up to 4 items
- notestring
The customer's note, shown on the order.
up to 1000 characters
- external_idstring
Your own id for this order. Unique per store and source_name.
1–255 characters
- source_namestring
A short name for your integration, e.g. "chatbot".
1–40 characters
- metadataobject
Up to 20 string key/value pairs of your own. Returned as sent, never shown to shoppers.
up to 20 keys
- preorderboolean
A pre-order, like the dashboard's Pre-order switch: a line may take units from the variant's incoming delivery when the shelf is empty, and the order is marked as a pre-order for the merchant. Products set to allow pre-orders take them anyway; this flag extends it to any product with a delivery on its way.
default false
- shipobject
Send the order to the courier right after creating it, like the dashboard's "Upload after creating". Needs the shipping:write scope. The order is created even if the courier refuses it: the answer then carries ship_error instead of shipment. Ignored by preview.
1 child field
- courier_idstring
A courier account from GET /v1/delivery/rates. Leave it out to use the order's courier, the routing rules or the default.
starts with cour_
Returns
200 OK · The order as it would be created. Order
- idstringRequired
starts with ord_
- objectstringRequired
always "order"
- numberstring or nullRequired
The number the merchant uses, e.g. "ORD-00042".
- statusstringRequired
pending→confirmed→ (with a courier)shipped→deliveredorreturned.scheduled,attempt_1…attempt_3,double,waitingandcancelledare set by the merchant's team;preparing,shipped,delivered,returnedanddeletedcome from the courier. New values may be added — treat an unknown one likepending.One of
pending,confirmed,scheduled,attempt_1,attempt_2,attempt_3,double,waiting,cancelled,preparing,shipped,delivered,returned,deleted - sourcestring
Where the order came from: storefront, dashboard, api or import.
- source_namestring or null
The integration that created it, as it named itself in source_name.
- external_idstring or null
The id the integration gave this order.
- needs_reviewstring or null
Why the merchant must check this order before it can go to a courier. city_unmatched — the city was not recognised. null when nothing needs checking.
- preorderboolean
Marked as a pre-order (the goods are on their way to the merchant).
- assigned_toobject or null
The teammate working this order.
2 child fields
- idstring
- namestring
- typestring
See OrderCreate.type. New values may be added.
One of
delivery,exchange,pickup,cash_collection - exchange_ofstring or null
The delivered order this exchange replaces goods from.
- collectobject or null
What the courier takes back, for an exchange or a pickup.
3 child fields
- stagestring or null
Where the collected goods are (pending until they come back).
- summarystring or null
The line the courier prints for the goods to collect.
- linesarray of objects
8 child fields
- original_line_item_idstring or null
- product_idstring or null
- variant_idstring or null
- titlestring
- variant_titlestring or null
- quantityinteger
- restockedinteger
Units put back into stock when they came back.
- written_offinteger
- metadataobject
Your own key/value pairs, returned as you sent them.
- customerobjectRequired
5 child fields
- idstring or null
- namestring
- phonestring or null
E.164.
- phone_2string or null
- emailstring or null
- shipping_addressAddressRequired
4 child fields
- countrystring
- regionobject
2 child fields
- codestring
- namestring
- cityobject
2 child fields
- codestring or null
- namestring
- address1string or null
- deliveryobject
7 child fields
- modestring or null
One of
home,pickup_point - labelstring or null
- courierobject or null
1 child field
- namestring
- pickup_pointobject or null
2 child fields
- idstring
- namestring or null
- tracking_codestring or null
- tracking_urlstring or null
The customer's tracking page for this order, on the store's address (https://<store>.myordexs.com/track/<code>). Send it to the customer: it shows every step of the delivery, in the store's language. Each order has its own private link, and it stays the same if the parcel is sent again. It stops working 3 days after the order is delivered or returned (the page then says the link has expired); a cancelled order has no tracking page. null in test mode.
uri
- shipped_atstring or null
ISO 8601 date-time, UTC
- line_itemsarray of objectsRequired
10 child fields
- idstring
- product_idstring or null
- variant_idstring or null
- titlestring
- variant_titlestring or null
- skustring or null
- quantityinteger
- unit_priceMoney
An amount of money.
amountis a decimal STRING with exactly the currency's number of decimals ("1250.00" in DZD, "12.500" in TND) — never parse it into a float.2 child fields
- amountstringRequired
- currencystringRequired
- totalMoney
An amount of money.
amountis a decimal STRING with exactly the currency's number of decimals ("1250.00" in DZD, "12.500" in TND) — never parse it into a float.2 child fields
- amountstringRequired
- currencystringRequired
- image_urlstring or null
- discount_codestring or null
The code the shopper used; null when none
- discount_namestring or null
The name of the discount applied
- offersarray of strings
Names of the offers applied.
- offer_idsarray of strings
The offers applied
- subtotalMoneyRequired
An amount of money.
amountis a decimal STRING with exactly the currency's number of decimals ("1250.00" in DZD, "12.500" in TND) — never parse it into a float.2 child fields
- amountstringRequired
- currencystringRequired
- shippingMoneyRequired
An amount of money.
amountis a decimal STRING with exactly the currency's number of decimals ("1250.00" in DZD, "12.500" in TND) — never parse it into a float.2 child fields
- amountstringRequired
- currencystringRequired
- discountMoney
An amount of money.
amountis a decimal STRING with exactly the currency's number of decimals ("1250.00" in DZD, "12.500" in TND) — never parse it into a float.2 child fields
- amountstringRequired
- currencystringRequired
- totalMoneyRequired
An amount of money.
amountis a decimal STRING with exactly the currency's number of decimals ("1250.00" in DZD, "12.500" in TND) — never parse it into a float.2 child fields
- amountstringRequired
- currencystringRequired
- paymentobjectRequired
6 child fields
- methodstring
"cod" (cash on delivery), "card" (paid in full online by card) or "card_deposit" (a deposit paid online by card, the rest in cash on delivery). More methods may be added.
- statusstring
unpaid: nothing received yet. pending: the shopper chose card and has not finished paying. partially_paid: a card deposit was received, the rest is collected on delivery. paid: fully paid (online, or the cash was recorded).
One of
unpaid,pending,partially_paid,paid - paid_atstring or null
ISO 8601 date-time, UTC
- amount_paidMoney
What the shopper already paid online toward the order.
2 child fields
- amountstringRequired
- currencystringRequired
- amount_to_collectMoney
What the courier collects in cash at delivery: total minus amount_paid.
2 child fields
- amountstringRequired
- currencystringRequired
- card_discountMoney
The store’s discount for paying by card, already included in discount and taken off total. Zero for cash on delivery.
2 child fields
- amountstringRequired
- currencystringRequired
- notestring or null
The customer's note at checkout.
- archivedboolean
- scheduled_forstring or null
ISO 8601 date-time, UTC
- livemodebooleanRequired
- created_atstringRequired
ISO 8601 date-time, UTC
- updated_atstringRequired
ISO 8601 date-time, UTC
Errors
Every error has the same shape. This endpoint can answer with:
- 401
authentication_required - 401
invalid_api_key - 402
plan_required - 403
insufficient_scope - 429
rate_limited - 400
invalid_request - 400
invalid_json - 400
unknown_field - 422
validation_failed - 409
idempotency_in_progress - 422
idempotency_key_reused - 422
out_of_stock - 422
region_unknown - 422
country_not_served - 422
delivery_unavailable - 403
store_paused - 403
store_restricted - 422
request_rejected
