Getting started
This guide takes you from an API key to your first order in OrderEx. You register a warehouse, create the example order that the API reference uses, ship one of its T-shirts, record the money captured for it, and read the order back. Every command works as written once you have set your key. The other guides continue with the same order.
What you need
- An API key from OrderEx.
- A shell with
curl7.84 or later, which can print a response header with-w. jq1.6 or later, which the commands use to keep ids from the responses.
The address and the key
| What | Value |
|---|---|
| Base URL | https://api.orderex.se/api/v1 |
| Authentication | The header X-Api-Key with your API key, on every request |
| Body format | JSON, sent with Content-Type: application/json |
Your systems authenticate with X-Api-Key only. POST /api/v1/auth/login and the other auth
endpoints in the reference are for the OrderEx portals, not for integrations.
A request without a key, or with a key that is wrong, expired or revoked, gets 401 Unauthorized.
Get an API key
OrderEx creates the API keys for your company. Ask your OrderEx contact for a key, one for each system that calls the API, such as your shop, your ERP and your warehouse system. Then each system can be given a new key, or lose its key, without affecting the others.
- A key belongs to one tenant, your company, and sees only that tenant's data.
- OrderEx stores only a hash of the key. The key is shown to you once, so store it in your secret store right away.
- A key can have an expiry date, and OrderEx can revoke it at any time.
Test and production
OrderEx has one address, and the key decides whose data you work with. There is no separate sandbox. To test without touching your production data, ask OrderEx for a test tenant: it has keys of its own, and the API keeps every tenant's data apart. Use the test tenant's key while you build, and your production key only in your production systems.
What you do
| Step | Call | What you keep |
|---|---|---|
| 1. Set your key | None | ORDEREX_API_KEY |
| 2. Register your warehouse | POST /api/v1/fulfillment/nodes | NODE_ID |
| 3. Create the example order | POST /api/v1/orders | ORDER_PATH |
| 4. Keep the order's line ids | GET /api/v1/orders/{id} | ORDER_ID, TSHIRT_LINE_ID and SHIPPING_LINE_ID |
| 5. Ship one T-shirt and the delivery | POST /api/v1/orders/{id}/shipments | SHIPMENT_ID and PARCEL_ID |
| 6. Record the capture | POST /api/v1/orders/{id}/payment-facts | Nothing |
| 7. Read the order back | GET /api/v1/orders/{id} | Nothing |
The other guides use the same shell variables, so keep your shell open, or set them again from the responses.
1. Set your key
Replace the value with your own key. It is the only thing you change in this guide.
export ORDEREX_API_KEY='paste-your-api-key-here'
2. Register your warehouse
Every shipment leaves a fulfillment node: a warehouse, a store or a third party logistics partner,
with the type warehouse, store or 3pl. Register each node once and keep its id. Registering
a node requires an Idempotency-Key header, a key you make up for this one request.
NODE_ID=$(curl -sS -X POST "https://api.orderex.se/api/v1/fulfillment/nodes" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: node-central-warehouse-1" \
-d '{"name": "Central warehouse", "type": "warehouse"}' | jq -r '.id')
echo "$NODE_ID"
OrderEx answers 201 Created with the node and its id. Without the header it answers
400 Bad Request, and NODE_ID is null. When you run the command again with the same key, OrderEx
answers 201 Created again with the same node and the same id, and registers nothing new.
A reliable integration explains how the key works.
A node name is unique in your tenant, so the same name with a new key gives 409 node-name-taken
and NODE_ID is null. Then read the id of the node you registered:
NODE_ID=$(curl -sS "https://api.orderex.se/api/v1/fulfillment/nodes" \
-H "X-Api-Key: $ORDEREX_API_KEY" | jq -r '.items[] | select(.name == "Central warehouse") | .id')
3. Create the example order
The order is from the shop channel webshop, with your own order number WEB-100234. It has two
lines: two black T-shirts at 249.00 SEK each, and home delivery at 49.00 SEK, 547.00 SEK in total.
Amounts are whole numbers in the currency's minor unit, so 249.00 SEK is 24900.
ORDER_PATH=$(curl -sS -X POST "https://api.orderex.se/api/v1/orders" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-o created-order.json \
-w '%header{location}' \
-d '{
"customerId": "C-20931",
"customerName": "Alex Example",
"customerEmail": "alex@example.com",
"customerType": "Consumer",
"currency": "SEK",
"pricesIncludeVat": true,
"channel": "webshop",
"externalOrderNumber": "WEB-100234",
"shippingAddress": {
"name": "Alex Example",
"street1": "Example Street 1",
"postalCode": "123 45",
"city": "Sample City",
"countryCode": "SE",
"country": "Sweden"
},
"lines": [
{
"articleNumber": "TSHIRT-BLK-M",
"description": "T-shirt, black, M",
"quantity": 2,
"unitPrice": 24900,
"vatRate": 25
},
{
"articleNumber": "SHIPPING",
"description": "Home delivery",
"lineType": "Shipping",
"quantity": 1,
"unitPrice": 4900,
"vatRate": 25
}
]
}')
echo "$ORDER_PATH"
cat created-order.json
OrderEx answers 201 Created. The Location header holds the order's path, which the command keeps
in ORDER_PATH, and the body holds the order's id and the order number OrderEx gave it:
{
"orderId": "5f8a2c1e-3b4d-4e6f-8a9b-1c2d3e4f5a6b",
"orderNumber": "ORD-20261114-7F3A9C21"
}
Your id and order number differ from the example. If you run the command again, OrderEx does not
create a second order: the channel and your order number already exist, so it answers
409 Conflict with the problem type order-already-exists, and Location still points at the
order you created. The next step works either way.
If ORDER_PATH is empty, the order was not created. Read created-order.json: it holds a problem
that says why, as Errors describes. The customer's name, e-mail address and shipping
address are personal data, and Fields and personal data lists every field that is.
4. Keep the order's line ids
Every fact about a line names the line by its id, so read the order and keep the ids of its two
lines.
ORDER_ID=${ORDER_PATH##*/}
curl -sS "https://api.orderex.se/api/v1/orders/$ORDER_ID" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-o order.json
TSHIRT_LINE_ID=$(jq -r '.lines[] | select(.articleNumber == "TSHIRT-BLK-M") | .id' order.json)
SHIPPING_LINE_ID=$(jq -r '.lines[] | select(.lineType == "Shipping") | .id' order.json)
echo "$TSHIRT_LINE_ID $SHIPPING_LINE_ID"
5. Ship one T-shirt and the delivery
Your warehouse has one T-shirt in stock. It sends that T-shirt now, together with the delivery, and
reports the shipment with its own shipment number wms-58213 as externalId.
curl -sS -X POST "https://api.orderex.se/api/v1/orders/$ORDER_ID/shipments" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-o shipment.json \
-d '{
"externalId": "wms-58213",
"nodeId": "'"$NODE_ID"'",
"shippedAt": "2026-11-16T14:05:00+01:00",
"lines": [
{"orderLineId": "'"$TSHIRT_LINE_ID"'", "quantity": 1},
{"orderLineId": "'"$SHIPPING_LINE_ID"'", "quantity": 1}
],
"parcels": [
{"trackingNumber": "00370712345678901234", "carrier": "Example Freight"}
]
}'
SHIPMENT_ID=$(jq -r '.id' shipment.json)
PARCEL_ID=$(jq -r '.parcels[0].id' shipment.json)
echo "$SHIPMENT_ID $PARCEL_ID"
OrderEx answers 201 Created with the shipment, its id and the id of each parcel. The same
shipment sent again, with the same externalId and content, returns 200 OK with the shipment as
first reported and changes nothing.
A shipment is checked as a whole, and nothing is stored when a check fails:
| Problem type | When |
|---|---|
shipment-node-unknown | nodeId is not one of your nodes. A deactivated node is accepted with the warning inactive_node |
shipment-line-not-on-order | A line is not a line of this order |
line-quantity-rule-violated | A line would ship more than ordered minus cancelled |
6. Record the capture
When the goods leave, your payment provider charges the customer for them: 249.00 SEK for the T-shirt and 49.00 SEK for the delivery, 298.00 SEK in all. Report the capture with the provider's transaction id, split per line.
curl -sS -X POST "https://api.orderex.se/api/v1/orders/$ORDER_ID/payment-facts" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "Captured",
"externalTransactionId": "cap-2026-7781",
"amount": 29800,
"currency": "SEK",
"paymentMethod": "card",
"providerName": "ExamplePay",
"occurredAt": "2026-11-16T14:12:00+01:00",
"allocations": [
{"orderLineId": "'"$TSHIRT_LINE_ID"'", "amount": 24900},
{"orderLineId": "'"$SHIPPING_LINE_ID"'", "amount": 4900}
]
}'
OrderEx answers 201 Created with the fact. OrderEx records the capture and never moves money:
nothing is sent to your payment provider.
amountis a whole number of at least 1, in the minor unit of the order's currency.currencymust be the order's currency, or OrderEx answers 422payment-currency-mismatch.externalTransactionIdis the provider's id of the transaction.allocationssay which lines the money is for, and add up toamount. They are optional, and Payment facts explains the rules for them.
7. Read the order back
curl -sS "https://api.orderex.se/api/v1/orders/$ORDER_ID" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
| jq '{id, orderNumber, status, totalAmount, lines: [.lines[] | {articleNumber, lineStatus, quantities}]}'
OrderEx answers 200 OK with the whole order, which the command shortens to the fields that
matter here:
{
"id": "5f8a2c1e-3b4d-4e6f-8a9b-1c2d3e4f5a6b",
"orderNumber": "ORD-20261114-7F3A9C21",
"status": "Draft",
"totalAmount": 54700,
"lines": [
{
"articleNumber": "TSHIRT-BLK-M",
"lineStatus": "PartiallyShipped",
"quantities": {"ordered": 2, "shipped": 1, "delivered": 0, "invoiced": 0, "returned": 0, "cancelled": 0, "remaining": 1}
},
{
"articleNumber": "SHIPPING",
"lineStatus": "Shipped",
"quantities": {"ordered": 1, "shipped": 1, "delivered": 0, "invoiced": 0, "returned": 0, "cancelled": 0, "remaining": 0}
}
]
}
| Field | In the example | What it is |
|---|---|---|
id | Your order's id | The id OrderEx uses in every path for the order |
orderNumber | Starts with ORD- | The order number OrderEx gave the order |
status | Draft | The order's status, which starts in the first status of your status flow |
totalAmount | 54700 | 547.00 SEK in minor units |
lines[].lineStatus | PartiallyShipped and Shipped | Where the line stands, derived from the facts reported on it |
lines[].quantities.shipped | 1 and 1 | How much of the line has left your warehouse |
lines[].quantities.remaining | 1 and 0 | What is left to ship: ordered minus cancelled minus shipped |
One T-shirt is shipped and one is not, so the T-shirt line is PartiallyShipped. The shipment did
not change the order's status: you move it yourself along your status flow, which you can read
with GET /api/v1/orders/status-flow. The default flow starts in Draft. The capture changes no
quantity; read what the money adds up to with GET /api/v1/orders/{id}/payment-facts.
Next
- Core concepts explains what OrderEx holds and how amounts, times and statuses work.
- The order lifecycle continues with the same order: the second T-shirt is cancelled, and the shipped one is delivered and returned.
- Payment facts records the authorization, the release and the refund that belong with the capture above.