Hoppa till huvudinnehåll

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 curl 7.84 or later, which can print a response header with -w.
  • jq 1.6 or later, which the commands use to keep ids from the responses.

The address and the key​

WhatValue
Base URLhttps://api.orderex.se/api/v1
AuthenticationThe header X-Api-Key with your API key, on every request
Body formatJSON, 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​

StepCallWhat you keep
1. Set your keyNoneORDEREX_API_KEY
2. Register your warehousePOST /api/v1/fulfillment/nodesNODE_ID
3. Create the example orderPOST /api/v1/ordersORDER_PATH
4. Keep the order's line idsGET /api/v1/orders/{id}ORDER_ID, TSHIRT_LINE_ID and SHIPPING_LINE_ID
5. Ship one T-shirt and the deliveryPOST /api/v1/orders/{id}/shipmentsSHIPMENT_ID and PARCEL_ID
6. Record the capturePOST /api/v1/orders/{id}/payment-factsNothing
7. Read the order backGET /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 typeWhen
shipment-node-unknownnodeId is not one of your nodes. A deactivated node is accepted with the warning inactive_node
shipment-line-not-on-orderA line is not a line of this order
line-quantity-rule-violatedA 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.

  • amount is a whole number of at least 1, in the minor unit of the order's currency.
  • currency must be the order's currency, or OrderEx answers 422 payment-currency-mismatch.
  • externalTransactionId is the provider's id of the transaction.
  • allocations say which lines the money is for, and add up to amount. 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}
}
]
}
FieldIn the exampleWhat it is
idYour order's idThe id OrderEx uses in every path for the order
orderNumberStarts with ORD-The order number OrderEx gave the order
statusDraftThe order's status, which starts in the first status of your status flow
totalAmount54700547.00 SEK in minor units
lines[].lineStatusPartiallyShipped and ShippedWhere the line stands, derived from the facts reported on it
lines[].quantities.shipped1 and 1How much of the line has left your warehouse
lines[].quantities.remaining1 and 0What 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.