Order (Order-Based)

Overview

Use the Order API - /deliveryexperience/order - to report when a Customer has purchased a set of products and is the beginning of their interactions with Shipium. This is the first major step in the Customer's order and delivery experience.

This is stage 1 in the Order - Shipment - Deliver sequence for Order-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 first 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.

API call and response examples are given below.

📘

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.

Order API

Standard order creation

This example shows registration of a Customer Order in the ShipTime API, including the optional partnerOrderId field.

📘

Note: Omitting partnerOrderId

You can omit the partnerOrderId field but, if you include it, you can reference this order later using your company's internal ID that you passed using this field. This will be convenient if you don't want to store an additional ID in your system.

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 a standard response:

{
  "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"
}

Order creation call with Partner-Specific Order ID

If you want to be able to refer to Shipium Orders using your company's order ID, you can provide a partnerOrderId value and use that to read order values. This essentially acts as an alias to the shipiumOrderId and they can be used interchangeably thereafter. This example shows the 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","partnerOrderId":"POID-12345"}'

This example shows the response:

{
  "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"
}

Retrieving an order

You can 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 use that alias. Otherwise, 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 of the above calls would be the identical order object shown below:

{
  "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.