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.
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.
Updated about 2 months ago