Skip to main content

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 curl 7.84 or later, which can print a response header with -w.

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​

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:

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[].idOne id per lineThe id you use to report facts about the line
lines[].lineStatusOpenWhere the line stands, derived from the facts reported on it
lines[].quantitiesordered 2 and 1The 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.