Hoppa till huvudinnehåll

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​

  1. The web shop creates each order when the customer checks out, with POST /api/v1/orders and the channel webshop.
  2. The stores create the orders taken in a store the same way, each store with its own channel, such as store-sthlm-01.
  3. 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 with PATCH /api/v1/orders/{id}/status.
  4. The warehouse system reports each shipment with its parcels when it leaves, with POST /api/v1/orders/{id}/shipments, and each return it receives, with POST /api/v1/orders/{id}/lines/{lineId}/returns.
  5. The carrier reports what happens to each parcel as tracking events, with POST /api/v1/orders/{id}/parcels/{parcelId}/tracking-events. The event Delivered makes the parcel's lines delivered.
  6. 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.
  7. 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_changed and order.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.

FactReported byWhere the request is
The order, with the channel webshopThe web shopGetting started, step 3
The shipment from the central warehouse, with its parcelThe warehouse systemGetting started, step 5
The captureThe payment providerGetting started, step 6
The cancellationThe ERPThe order lifecycle, step 1
The delivery, as the tracking event DeliveredThe carrierThe order lifecycle, step 2
The returnThe warehouse systemThe order lifecycle, step 3
The authorization, the release and the refundThe payment providerPayment 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 orderStore order
ChannelwebshopThe store's own channel, such as store-sthlm-01
Who creates the orderThe web shopThe store's till
The node the shipment leavesThe central warehouse, a node of type warehouseThe store, registered once as a node of type store
Who reports the shipmentThe warehouse systemThe store's till, with the store's node as nodeId
Who reports the payment factsThe web shop's payment providerThe 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 orderClick and collect
Channelwebshopwebshop, since the customer ordered in the web shop
Shipping addressThe customer's homeThe pick-up store
The node the shipment leavesThe central warehouseThe central warehouse. The pick-up store is not the node, since nothing leaves it
What the tracking event Delivered meansThe parcel reached the customerThe 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}/shipments answers 400 Bad Request.
  • A payment reported without a shipment is money captured for goods that were not shipped, so Control flags it as captured_not_shipped in GET /api/v1/control/imbalances.

Keep counter sales in your till and your ERP.

Next​

The order lifecycle reports each fact on the example order.