Skip to main content

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.

FactReported byCall
OrderedYour shopPOST /api/v1/orders
CancelledYour shop or ERPPOST /api/v1/orders/{id}/lines/{lineId}/cancellations
ShippedYour warehouse systemPOST /api/v1/orders/{id}/shipments
DeliveredYour carrier integrationPOST /api/v1/orders/{id}/parcels/{parcelId}/tracking-events
ReturnedYour returns handlingPOST /api/v1/orders/{id}/lines/{lineId}/returns
MoneyYour payment integrationPOST /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 422 invalid-amount, and nothing is written.
  • An amount sent as a string, such as "42244", gives 400 invalid-request.

VAT​

Every order says whether its prices include VAT, and every line has its own VAT rate.

  • pricesIncludeVat is true when the unit prices include VAT and false when they exclude it.
  • vatRate is 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 without vatRate, gives 422 vat-required, whose errors name 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's shippedAt, 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 422 occurred-at-in-future.
  • recordedAt is when OrderEx received the fact.

Order status and line status​

An order has two kinds of status, and they answer different questions.

Order statusLine lineStatus
What it saysWhere the order is in your processWhere the goods on the line stand
ValuesThe statuses of your status flow, such as Draft, Confirmed and ShippedOpen, PartiallyShipped, Shipped, Delivered, PartiallyReturned, Returned and Cancelled
How it changesYou move it with PATCH /api/v1/orders/{id}/status, along the transitions of your status flowOrderEx 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.

  • channel and externalOrderNumber identify the order in your shop. The number is unique per channel, so the same order cannot be created twice: a second create gives 409 order-already-exists, with the existing order's id.
  • Each fact's externalId is 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 with GET /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.