Getting started
This guide takes you from an API key to your first order in OrderEx. You create the example order that the API reference uses, and read it back. Every command works as written once you have set your key.
What you need
- An API key from OrderEx.
- A shell with
curl7.84 or later, which can print a response header with-w.
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
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. 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. Step 3 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.
3. Read the order back
ORDER_ID=${ORDER_PATH##*/}
curl -sS "https://api.orderex.se/api/v1/orders/$ORDER_ID" \
-H "X-Api-Key: $ORDEREX_API_KEY"
OrderEx answers 200 OK with the whole order. These are the fields to look at first:
| 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[].id | One id per line | The id you use to report facts about the line |
lines[].lineStatus | Open | Where the line stands, derived from the facts reported on it |
lines[].quantities | ordered 2 and 1 | The quantities ordered, cancelled, shipped, delivered and returned |
Which status a new order starts in depends on your status flow, which you can read with
GET /api/v1/orders/status-flow. The default flow starts in Draft.
Next
- Core concepts explains what OrderEx holds and how amounts, times and statuses work.
- The order lifecycle reports a cancellation, a shipment, a delivery and a return on the order you just created.