Order (Delivery Estimate-Based)

Overview

Use the Order API - /deliveryexperience/order - to report when a Customer has purchased a given product, referencing a prior set of Estimated Delivery Dates.

This is stage 2 in the Product View - Order - Shipment - Deliver sequence for Estimate-Based Delivery.

Registering an order with ShipTime enables us to "start the clock" on order-to-shipment and shipment-to-delivery times and is a critical step in tracking your customer delivery experience. The Order API takes information about the customer's shipping postal code, order details such as the time the order was placed, and an array of items in the order with their quantities and associated deliveryEstimateIds.

API request and response examples are shown below.

Order API

📘
Authentication for API calls
In the cURL examples on this page, the environment variable AUTHSTRING is used to handle authorization. The recipe below shows how to set it correctly for both API Key and OAuth users.

🦉

Authenticating for Curl

Open Recipe

Standard Order Creation call and response

This example shows a standard Order Creation cURL request:

curl --request POST \
  --url <<api_url>>/api/v1/deliveryexperience/order \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data '{"destinationAddress":{"addressType":"residential","postalCode":"98101","countryCode":"US"},"orderItemQuantities":[{"productId":"9780374533557","quantity":1}],"orderedDateTime":"2020-03-27T22:14+0000"}'

This example shows the response:

{
  "destinationAddress": 
  {
      "addressType":"residential",
      "postalCode":"98101",
      "countryCode":"US"
  },
  "orderItemQuantities":[
    {
       "deliveryEstimateId":"0b3d140a-525b-43a7-896c-cdc381580d61",
       "productId":"9780374533557",
       "quantity":1
    }
  ],
  "shipOption":"Standard",
  "orderedDateTime":"2020-03-27T22:14+0000",
  "shipiumOrderId":"4dc43fff-c3af-4d7b-8a18-e01f2b4cb312"
}

Order Creation request and response with partner-specific order ID

If you want the ability to refer to Shipium Orders using your company's order ID, you can provide a partnerOrderId value and use that to read order values. It essentially acts as an alias to the shipiumOrderId and they can be used interchangeably thereafter.

This example shows the Order Creation cURL request using partnerOrderId:

curl --request POST \
  --url <<api_url>>/api/v1/deliveryexperience/order \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data '{"destinationAddress":{"addressType":"residential","postalCode":"98101","countryCode":"US"},"orderItemQuantities":[{"productId":"9780374533557","quantity":1}],"orderedDateTime":"2020-03-27T22:14+0000","partnerOrderId":"POID-12345"}'

This example shows the response:

{
  "destinationAddress": 
  {
      "addressType":"residential",
      "postalCode":"98101",
      "countryCode":"US"
  },
  "orderItemQuantities":[
    {
      "deliveryEstimateId":"0b3d140a-525b-43a7-896c-cdc381580d61",
      "productId":"9780374533557",
      "quantity":1
    }
  ],
  "shipOption":"Standard",
  "orderedDateTime":"2020-03-27T22:14+0000",
  "shipiumOrderId":"4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
  "partnerOrderId":"POID-12345"
}

Retrieving an order

You can also retrieve a previous order if you lost the information or need to get it again for some other reason. If you provided a partnerOrderId as part of the call, you can either use that alias or use the previously returned shipiumOrderId.

This example cURL request uses the sample partnerOrderId "POID-12345" to load a prior order:

curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/order/POID-12345 \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json'

This example cURL request uses the shipiumOrderId to retrieve the same order:

curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/order/4dc43fff-c3af-4d7b-8a18-e01f2b4cb312 \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json'

The response to either request would be the identical order object from above:

{
  "destinationAddress": 
  {
      "addressType":"residential",
      "postalCode":"98101",
      "countryCode":"US"
  },
  "orderItemQuantities":[
    {
      "productId":"9780374533557",
      "quantity":1
    }
  ],
  "shipOption":"Standard",
  "orderedDateTime":"2020-03-27T22:14+0000",
  "shipiumOrderId":"4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
  "partnerOrderId":"POID-12345"
}

📘
More information on the API responses
As with all Shipium API responses, this API follows the API Response Codes standards unless otherwise specified.