Core concepts
Read this page once before you build. It explains the model behind every endpoint, so the other guides can be short.
Facts about order lines
OrderEx holds the facts of every order line after checkout: how much was ordered, cancelled, shipped, delivered and returned, and how much money was authorized, captured, refunded and released. Your systems report each fact when it happens, and OrderEx keeps them side by side, so that the money follows the goods and you can see where they do not match.
| Fact | Reported by | Call |
|---|---|---|
| Ordered | Your shop | POST /api/v1/orders |
| Cancelled | Your shop or ERP | POST /api/v1/orders/{id}/lines/{lineId}/cancellations |
| Shipped | Your warehouse system | POST /api/v1/orders/{id}/shipments |
| Delivered | Your carrier integration | POST /api/v1/orders/{id}/parcels/{parcelId}/tracking-events |
| Returned | Your returns handling | POST /api/v1/orders/{id}/lines/{lineId}/returns |
| Money | Your payment integration | POST /api/v1/orders/{id}/payment-facts |
A fact is reported once and is never edited. Each fact carries your own id for it, so sending it again changes nothing. A shipment reported by mistake is voided, and the right one is reported as a new fact. OrderEx records facts and never acts on them: it does not move money, book a shipment or send e-mail.
Your tenant
Your company is a tenant in OrderEx. Every API key belongs to one tenant, and every call sees and changes only that tenant's data. An id from another tenant is not found.
Ids
OrderEx gives every order, line, shipment, parcel and fact an id, a GUID such as
5f8a2c1e-3b4d-4e6f-8a9b-1c2d3e4f5a6b. You use these ids in paths, so keep the order's id and its
line ids when you create an order.
Your own ids go in the body: the order's externalOrderNumber with its channel, and the
externalId of each fact. OrderEx compares them exactly. A fact's id must not start with
orderex:, in any letter case, since that prefix is reserved for OrderEx.
Amounts
Every amount is a whole number in the minor unit of the order's currency. 249.00 SEK is 24900,
and 547.00 SEK is 54700.
- The currencies are SEK, NOK, DKK, EUR, GBP, USD and ISK, each with two decimals in the API. Any
other currency gives 422
unsupported-currency. - An amount with decimals, such as
422.44, gives 422invalid-amount, and nothing is written. - An amount sent as a string, such as
"42244", gives 400invalid-request.
VAT
Every order says whether its prices include VAT, and every line has its own VAT rate.
pricesIncludeVatistruewhen the unit prices include VAT andfalsewhen they exclude it.vatRateis the line's rate in percent, from 0 to 100 with at most two decimals. A shipping or fee line has its own rate, and a line without VAT has 0.- An order without
pricesIncludeVat, or a line withoutvatRate, gives 422vat-required, whoseerrorsname every missing field.
OrderEx computes each line's total excluding VAT, its VAT and its total including VAT once, and
returns them in the line's pricing.
Times
- Send every time in ISO 8601 with an offset, such as
2026-11-16T14:05:00+01:00. - OrderEx returns times in UTC, such as
2026-11-16T13:05:00Z, and the times of facts with microseconds. - A fact's
occurredAt, or a shipment'sshippedAt, is when it happened in your system. It may be in the past, and at most 5 minutes after OrderEx's clock, or OrderEx answers 422occurred-at-in-future. recordedAtis when OrderEx received the fact.
Order status and line status
An order has two kinds of status, and they answer different questions.
Order status | Line lineStatus | |
|---|---|---|
| What it says | Where the order is in your process | Where the goods on the line stand |
| Values | The statuses of your status flow, such as Draft, Confirmed and Shipped | Open, PartiallyShipped, Shipped, Delivered, PartiallyReturned, Returned and Cancelled |
| How it changes | You move it with PATCH /api/v1/orders/{id}/status, along the transitions of your status flow | OrderEx derives it from the line's quantities after every fact |
Facts never move the order status. A shipment does not make the order Shipped, so an order can
show Delivered while all its lines are Returned. Read your status flow with
GET /api/v1/orders/status-flow.
Linking to your shop and ERP
OrderEx keeps your own references, so you can find an order from your systems and back.
channelandexternalOrderNumberidentify the order in your shop. The number is unique per channel, so the same order cannot be created twice: a second create gives 409order-already-exists, with the existing order's id.- Each fact's
externalIdis your id of that fact, such as the warehouse's shipment number. - An order's integrations hold its ids in other systems, such as the sales order in your ERP. Set
one with
PUT /api/v1/orders/{id}/integrations/{type}/{integrationId}and read them withGET /api/v1/orders/{id}/integrations?type=erp.
INTEGRATION_TYPE=erp
INTEGRATION_ID=example-erp
curl -sS -X PUT "https://api.orderex.se/api/v1/orders/$ORDER_ID/integrations/$INTEGRATION_TYPE/$INTEGRATION_ID" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "SO-48213",
"displayName": "Sales order 48213",
"status": "Synced",
"lastSyncedAt": "2026-11-14T09:15:00Z"
}'
erp is your name for the kind of system and example-erp your name for the system itself. Setting
the same pair again replaces the reference.
Next
The order lifecycle reports each fact on the example order.