A typical retailer integration
A retailer with a web shop, stores, an ERP, a warehouse, a carrier and a payment provider connects each of these systems to OrderEx. Each system reports the facts it knows first, and OrderEx keeps them side by side on the order's lines, so that the money follows the goods. This guide shows who reports what, first for a web order and then for what differs in a store order and in click and collect.
Who reports what
- The web shop creates each order when the customer checks out, with
POST /api/v1/ordersand the channel webshop. - The stores create the orders taken in a store the same way, each store with its own channel, such as store-sthlm-01.
- The ERP reports a line that cannot be delivered as a cancellation, with
POST /api/v1/orders/{id}/lines/{lineId}/cancellations, and moves the order along your status flow withPATCH /api/v1/orders/{id}/status. - The warehouse system reports each shipment with its parcels when it leaves, with
POST /api/v1/orders/{id}/shipments, and each return it receives, withPOST /api/v1/orders/{id}/lines/{lineId}/returns. - The carrier reports what happens to each parcel as tracking events, with
POST /api/v1/orders/{id}/parcels/{parcelId}/tracking-events. The eventDeliveredmakes the parcel's lines delivered. - The payment provider reports the authorization at checkout, the capture when the goods
leave, and any release or refund, with
POST /api/v1/orders/{id}/payment-facts. - OrderEx calls your webhook receiver, such as the ERP, when an order is created, gets a line,
changes its metadata or changes status:
order.created,order.line_added,order.metadata_changedandorder.status_changed. Shipments, tracking events, returns and payment facts are not sent back as webhooks; read them from the order, as Reading data shows.
The systems do not call OrderEx themselves: your integration for each system does, with its own API key, as Getting started recommends. OrderEx only records the facts. It does not move money, book a shipment or send e-mail.
The web order
The web order is the example order of Getting started, and every request it needs is there and in The order lifecycle and Payment facts.
| Fact | Reported by | Where the request is |
|---|---|---|
| The order, with the channel webshop | The web shop | Getting started, step 3 |
| The shipment from the central warehouse, with its parcel | The warehouse system | Getting started, step 5 |
| The capture | The payment provider | Getting started, step 6 |
| The cancellation | The ERP | The order lifecycle, step 1 |
The delivery, as the tracking event Delivered | The carrier | The order lifecycle, step 2 |
| The return | The warehouse system | The order lifecycle, step 3 |
| The authorization, the release and the refund | The payment provider | Payment facts |
The store order and click and collect below use the same requests. Only what differs is listed.
A store order
The customer orders in a store, and the store ships the goods from its own stock to the customer's home.
| Web order | Store order | |
|---|---|---|
| Channel | webshop | The store's own channel, such as store-sthlm-01 |
| Who creates the order | The web shop | The store's till |
| The node the shipment leaves | The central warehouse, a node of type warehouse | The store, registered once as a node of type store |
| Who reports the shipment | The warehouse system | The store's till, with the store's node as nodeId |
| Who reports the payment facts | The web shop's payment provider | The store's payment provider |
The parcel, the carrier's tracking events and the return are reported as for the web order.
One channel per store
Give each store a channel of its own, such as store-sthlm-01 and store-gbg-02. externalOrderNumber
is unique per channel, so two stores whose tills both number their orders from 1001 would collide in
one shared channel: the second store's order 1001 gives 409 order-already-exists, and OrderEx
points at the first store's order instead. With one channel per store, each store's numbers are its
own.
A channel is a code of lowercase letters, digits, ., _ and - that starts with a letter or a
digit, at most 50 characters.
Click and collect
The customer orders in the web shop and collects the goods in a store. The warehouse sends the goods to the store as a real parcel with a carrier.
| Web order | Click and collect | |
|---|---|---|
| Channel | webshop | webshop, since the customer ordered in the web shop |
| Shipping address | The customer's home | The pick-up store |
| The node the shipment leaves | The central warehouse | The central warehouse. The pick-up store is not the node, since nothing leaves it |
What the tracking event Delivered means | The parcel reached the customer | The parcel reached the pick-up store |
The carrier reports Delivered when the parcel arrives at the store, and the parcel's lines become
delivered then. OrderEx does not record that the customer collected the goods: there is no fact for
it today, so a parcel that waits in the store looks the same as one the customer has collected.
Counter sales are not sent
A sale over the counter, where the customer pays and takes the goods at once, is not supported today. Do not send counter sales to OrderEx.
- A shipment needs at least one parcel with a tracking number and a carrier, and goods that leave
over the counter have neither. Without a parcel,
POST /api/v1/orders/{id}/shipmentsanswers400 Bad Request. - A payment reported without a shipment is money captured for goods that were not shipped, so
Control flags it as
captured_not_shippedinGET /api/v1/control/imbalances.
Keep counter sales in your till and your ERP.
Next
The order lifecycle reports each fact on the example order.