Delivery Experience Flow: Using Delivery Estimates


The Shipium API helps you to provide better information to your Customers on your company's product pages, and helps you understand the timing of each step in your fulfillment process. To do this, your systems will call into the Shipium API at the four points in your Customer's Delivery Experience shown in this table:

1. You show a Customer a product

You call the endpoint to register a page view and get a deliveryEstimateDate and corresponding deliveryEstimateId. This Id is used in future calls, so store it in a session object or similar associated with the Customer visit.
2. Customer orders and checks out

After a Customer purchases a product from your site, you call the endpoint to create a representation of your order and provide a map of deliveryEstimateIds to quantities in the order, plus other order properties.

For simplicity, you can also pass your company's orderId to use as an alias in future calls.
3. Customer's shipment leaves your warehouse

When your Fulfillment Center ships a package to a customer, you call one of two endpoints depending on the situation:

- If the shipment contains exactly what was in a prior order, you call the first endpoint shown for simplicity.
- If you are shipping a package that contains the complete or partial contents of multiple orders, you can specify the contents of the shipment using the second endpoint.

4. Customer's shipment is delivered

When your Customer's shipment is delivered by a carrier, you call the endpoint to update the shipment's delivery date/time with a PUT to the existing shipment.

These four stages are described in detail in the following pages.


Important note on passing IDs!

Throughout this API, when there is a need for a unique ID that represents a partner entity, we give our Partners the choice of providing their own ID or retrieving a unique ID from us.

We refer to IDs that you provide as partner, and IDs that we provide as shipium.

They are interchangeable wherever they are used. It is up to you to decide which pattern you prefer.

For example, when retrieving information about a Customer's order that you had previously POSTed using your own ID, you can either use your own ID or the Shipium ID mapping to that order.

In this case, both of the following calls will return the same information:

  • /api/v1/deliveryexperience/order/{partnerOrderId}
  • /api/v1/deliveryexperience/order/{shipiumOrderId}