Skip to main content

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 parameterWhat it does
statusOnly orders in this status, such as Confirmed, matched exactly
customerIdOnly orders for this customer id, matched exactly
searchOrders whose order number or customer name contains the text, in any letter case
page and pageSizeWhich 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 parameterWhat it does
eventTypeOnly events of this type, such as order.status_changed or orders.shipment_reported.v1
from and toOnly events that happened in this period, as ISO 8601 times
page and pageSizeWhich 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:

CallReturns
GET /api/v1/orders/{id}/payment-factsPayment facts and their sums, see Payment facts
GET /api/v1/orders/{id}/integrationsYour references to the order in other systems
GET /api/v1/orders/{orderId}/webhook-deliveriesThe webhooks sent about the order, see Webhooks

Pagination​

Lists come in two forms. Use the one the endpoint has.

Pages​

EndpointDefaultLargest page
GET /api/v1/ordersPage 1, 20 per page100 per page
GET /api/v1/orders/{id}/timelinePage 1, 20 per page100 per page
GET /api/v1/orders/{orderId}/webhook-deliveriesPage 1, 20 per pageNo cap
GET /api/v1/webhooks/{webhookId}/deliveriesPage 1, 20 per pageNo 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​

EndpointDefaultAllowed
GET /api/v1/orders/{id}/shipmentsoffset 0, limit 50offset 0 or more, limit 1 to 200
GET /api/v1/orders/{id}/parcels/{parcelId}/tracking-eventsoffset 0, limit 50offset 0 or more, limit 1 to 200
GET /api/v1/fulfillment/nodesoffset 0, limit 50offset 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.