Delivery Experience Flow: Using Delivery Estimates

Understand the four stages in your customers' delivery experience.

About your customers' delivery experience

Shipium's Delivery Experience application programming interface (API) helps you to provide better information to your customers on your organization's product pages. It also helps you understand the timing of each stage in your organization's fulfillment process and your customers' delivery experience.

Customer stages and corresponding API endpoints

This process entails your system(s) calling the selected API at four stages in your customers' delivery experience, as shown in the following table, which also includes each applicable API endpoint.

Customer stageAPI endpoint
1. Product View. Your customer views a product on your organization's site.

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. Order. Your customer orders and checks out.

After a customer purchases a product from your site, your system calls 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 organization's orderId to use as an alias in future calls.
3. Shipment. Your customer's shipment leaves your warehouse.

When your Fulfillment Center (FC), or origin, ships a package to a customer, your system calls 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're 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. Delivery. Your customer's shipment is delivered.

When your customer's shipment is delivered by a carrier, your system calls 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 their own pages:


Important note on passing IDs!

Throughout this API, when there is a need for a unique ID that represents your organization, you have the choice of providing your own ID or retrieving a unique ID from Shipium.

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

The IDs are interchangeable wherever they're used, and which one you select is up to your organization's preference.

For example, when retrieving information about a customer's order that you had previously POSTed using your organization's own ID, you can either use your organization's 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}