Reading data
Everything your systems report can be read back. This guide shows the reads you need most often and how to page through a list.
Find orders
GET /api/v1/orders lists your orders, newest first.
| Query parameter | What it does |
|---|---|
status | Only orders in this status, such as Confirmed, matched exactly |
customerId | Only orders for this customer id, matched exactly |
search | Orders whose order number or customer name contains the text, in any letter case |
page and pageSize | Which page to return, see Pagination below |
curl -sS "https://api.orderex.se/api/v1/orders?customerId=C-20931&page=1&pageSize=50" \
-H "X-Api-Key: $ORDEREX_API_KEY"
Each item is a summary of the order with its id, orderNumber, externalOrderNumber, status,
totalAmount and lineCount. Read the whole order, with its lines and quantities, with
GET /api/v1/orders/{id}.
search does not look at your own order number. To find an order from your shop, keep the
orderId OrderEx returned when you created it. A create that is sent again also returns the
existing order's id, in a 409 order-already-exists.
Read an order's timeline
The timeline is the order's history: every change and every fact, oldest first.
curl -sS "https://api.orderex.se/api/v1/orders/$ORDER_ID/timeline?eventType=order.status_changed" \
-H "X-Api-Key: $ORDEREX_API_KEY"
| Query parameter | What it does |
|---|---|
eventType | Only events of this type, such as order.status_changed or orders.shipment_reported.v1 |
from and to | Only events that happened in this period, as ISO 8601 times |
page and pageSize | Which page to return |
A fact is placed where it happened in your system, by its occurredAt or shippedAt, and every
other event where OrderEx recorded it. Each entry's own occurredAt is when OrderEx recorded it, and
initiatedBy says which API key or portal user made the change.
Read shipments and tracking
curl -sS "https://api.orderex.se/api/v1/orders/$ORDER_ID/shipments?externalId=wms-58213" \
-H "X-Api-Key: $ORDEREX_API_KEY"
GET /api/v1/orders/{id}/shipments lists the order's shipments with their lines and parcels, in
the order they were shipped. Voided shipments are listed too, with status Voided. externalId
finds a shipment by your own id, matched exactly. Read one shipment with
GET /api/v1/orders/{id}/shipments/{shipmentId}.
Each parcel has its latestTracking, and GET /api/v1/orders/{id}/parcels/{parcelId}/tracking-events
returns its whole tracking history.
Other reads on an order:
| Call | Returns |
|---|---|
GET /api/v1/orders/{id}/payment-facts | Payment facts and their sums, see Payment facts |
GET /api/v1/orders/{id}/integrations | Your references to the order in other systems |
GET /api/v1/orders/{orderId}/webhook-deliveries | The webhooks sent about the order, see Webhooks |
Pagination
Lists come in two forms. Use the one the endpoint has.
Pages
| Endpoint | Default | Largest page |
|---|---|---|
GET /api/v1/orders | Page 1, 20 per page | 100 per page |
GET /api/v1/orders/{id}/timeline | Page 1, 20 per page | 100 per page |
GET /api/v1/orders/{orderId}/webhook-deliveries | Page 1, 20 per page | No cap |
GET /api/v1/webhooks/{webhookId}/deliveries | Page 1, 20 per page | No cap |
page starts at 1. For orders and the timeline, a pageSize above 100 returns 100 per page, and
one below 1 returns 1. The webhook delivery lists return the pageSize you ask for, so keep it at
100 or below and ask for more pages instead. The response has items, page, pageSize and totalCount, and the order
and timeline lists also have totalPages, hasNextPage and hasPreviousPage. Ask for the next page
while hasNextPage is true.
Offset and limit
| Endpoint | Default | Allowed |
|---|---|---|
GET /api/v1/orders/{id}/shipments | offset 0, limit 50 | offset 0 or more, limit 1 to 200 |
GET /api/v1/orders/{id}/parcels/{parcelId}/tracking-events | offset 0, limit 50 | offset 0 or more, limit 1 to 200 |
GET /api/v1/fulfillment/nodes | offset 0, limit 50 | offset 0 or more, limit 1 to 200 |
A value outside what is allowed gives 400. The response has items, offset, limit and
totalCount. Ask for the next items with offset plus limit while that is below totalCount.
GET /api/v1/fulfillment/nodes also takes isActive, to list only active or only deactivated nodes.
Next
Errors explains every error response and what to do about it.