Product View (Delivery Estimate Based)
Display a delivery estimate date on your customer's product page view.
About the Delivery Experience Product View API
Use the Delivery Experience Product View Application Programming Interface (API), /deliveryexperience/productview, to:
- report when a product page has been shown to a customer; and
- retrieve a delivery estimate date, or Customer Delivery Estimate, to show the customer.
This is stage 1 in the Delivery Experience flow for using delivery estimates:
- Product View
- Order
- Shipment
- Deliver
How to use the Product View API
Call this API each time that a product is displayed to a customer, both to track page loads and to display an appropriate Customer Delivery Estimate.
While the full API has many option components for certain client installations, three are critical to include in every API call:
customerCountryCode
;customerPostalCode
; andproductId
.
These allow Shipium to return a Customer Delivery Estimate that is specific to your customer and the product they viewed.
The next section includes example client uniform resource locator (cURL) requests and JavaScript Object Notation (JSON) responses for this API call.
Handling no response
When implementing your company's integration, make sure that you have a reasonable fallback for the case in which either our service is down (rare, but no one can promise never) or where no information is available.
In the former case, you may not retrieve any value.
In the latter case, you will get a 204 response from the API.Don't let our mistakes or lack of data prevent your customers from purchasing!
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 call and response
The examples in this section show the most common way of calling the /deliveryexperience/productview API and a typical response.
This example shows a standard cURL request:
curl --request POST \
--url <<api_url>>/api/v1/deliveryexperience/productview \
--header 'accept: application/json' \
--header $AUTHSTRING \
--header 'content-type: application/json' \
--data '{"customerCountryCode":"US","customerPostalCode":"98036"}'
And here is the body JSON expanded:
{
"customerCountryCode": "US",
"customerPostalCode": "98036"
}
This example shows a standard response:
{
"deliveryEstimateId": "074f087a-8de4-4d9f-8eb7-d3fc3b5c4404",
"requestDate": "2022-05-31T20:52:52.802Z",
"shipEstimateDate": "2022-06-01T20:00:00-04:00",
"deliveryEstimateDate": "2022-06-03T20:00:00-04:00",
"estimatedTimeInTransitDays": 2,
"customerCountryCode": "US",
"customerPostalCode": "98036",
"shippingOrigin": {
"countryCode": "US",
"postalCode": "98327",
"shipiumOriginId": "3adcd9f9-06de-4620-894f-7b1e6db1a815"
},
"requestDateOverride": null,
"shipDateOverride": null
}
Call and response with additional options
In some integrations, Partners may need to pass additional shipping options due to a specialized fulfillment configuration. An example of such a cURL request is shown below:
curl --request POST \
--url <<api_url>>/api/v1/deliveryexperience/productview \
--header 'accept: application/json' \
--header $AUTHSTRING \
--header 'content-type: application/json' \
--data '{"customerCountryCode":"US","customerPostalCode":"98101","options":{"shippingOptions":{"fromCountryCode":"US","fromPostalCode":"63376","shipOption":"TwoDay"}}}'
Here is the JSON body expanded:
{
"customerCountryCode": "US",
"customerPostalCode": "98101",
"options":
{
"shippingOptions":
{
"fromCountryCode": "US",
"fromPostalCode": "63376",
"shipOption": "TwoDay"
}
}
In this case, the Partner is providing an explicit ship-from Fulfilment Center location using a fromCountryCode
and fromPostalCode
pair and replacing the default shipOption
that was shown to the customer with "TwoDay".
This example shows the response when extra options are used:
{
"deliveryEstimateId": "0b3d140a-525b-43a7-896c-cdc381580d61",
"customerCountryCode": "us",
"deliveryEstimateDate": "2019-10-31T00:00:00.000000Z",
"customerPostalCode": "98101",
"options": {
"shippingOptions": {
"fromCountryCode": "US",
"fromPostalCode": "87121",
"shipOption": "Standard"
}
}
}
Call and response with advanced options
In some situations, Partners may need to pass additional shipping options due to specialized fulfillment information. In such a case, the caller may have specific information about when the request should be seen as effective by (such as showing a customer an estimate from the perspective of a future day they might purchase a not-yet-released item) and/or information about when the shipment is likely to leave the warehouse.
These cases are more complex, so think carefully before using them in your integration.
key name | overview | value type |
---|---|---|
requestDateOverride | Optional date-time value causing the call to be treated as though it had been called at the time specified. Not passing this value defaults to the current date-time. | ISO-8601 date-time value |
shipDateOverride | Optional date-time value causing the call to override the calculated shipDate with the specified shipDate. | ISO-8601 date-time value |
Using shipDateOverride in relation to other times
Note that
shipDateOverride
must always be greater thanrequestDateOverride
if it is being used or later thannow
otherwise. (You can't ship earlier than a pageView!)
Example: Ship Option / Request Date / Ship Estimate Date Override(s)
This example shows the response when extra options are used:
curl --request POST \
--url <<api_url>>/api/v1/deliveryexperience/productview \
--header 'accept: application/json' \
--header $AUTHSTRING \
--header 'content-type: application/json' \
--data '{"customerCountryCode": "US","customerPostalCode": "98036","requestDateOverride": "2022-04-04T14:45:35.721Z","shipDateOverride": "2022-04-05T14:40:35.721Z","options": {"shippingOptions": {"shipOption": "NextDay"}'
Here is the JSON body expanded:
{
"customerCountryCode": "US",
"customerPostalCode": "98036",
"requestDateOverride": "2022-04-04T14:45:35.721Z",
"shipDateOverride": "2022-04-05T14:40:35.721Z",
"options": {
"shippingOptions": {
"shipOption": "NextDay"
}
}
}
This example shows the response when extra options are used:
{
"deliveryEstimateId": "f88bdfbd-ca61-4cfe-b12f-3056404923f9",
"requestDate": "2022-04-04T14:45:35.721Z",
"shipEstimateDate": "2022-04-05T10:40:35.721-04:00",
"deliveryEstimateDate": "2022-04-06T20:00:00-04:00",
"estimatedTimeInTransitDays": 1,
"customerCountryCode": "US",
"customerPostalCode": "98036",
"shippingOrigin": {
"countryCode": "US",
"postalCode": "98327",
"shipiumOriginId": "3adcd9f9-06de-4620-894f-7b1e6db1a815"
},
"requestDateOverride": "2022-04-04T14:45:35.721Z",
"shipDateOverride": "2022-04-05T14:40:35.721Z",
"options": {
"shippingOptions": {
"shipOption": "NextDay"
}
}
}
Example: Ship From Country Postal Override
curl --request POST \
--url <<api_url>>/api/v1/deliveryexperience/productview \
--header 'accept: application/json' \
--header $AUTHSTRING \
--header 'content-type: application/json' \
--data '{"customerCountryCode": "US","customerPostalCode": "92801" "options": {"shippingOptions": {"fromCountryCode": "US","fromPostalCode": "97005"}}}'
Here is the JSON body expanded:
{
"customerCountryCode": "US",
"customerPostalCode": "92801",
"options": {
"shippingOptions": {
"fromCountryCode": "US",
"fromPostalCode": "97005"
}
}
}
This example shows the response when extra options are used:
{
"deliveryEstimateId": "9e1ab8b6-07f5-440a-853f-c75529c91bd1",
"requestDate": "2022-05-31T21:00:14.427Z",
"shipEstimateDate": "2022-06-01T20:00:00-04:00",
"deliveryEstimateDate": "2022-06-06T20:00:00-04:00",
"estimatedTimeInTransitDays": 5,
"customerCountryCode": "US",
"customerPostalCode": "92801",
"shippingOrigin": {
"countryCode": "US",
"postalCode": "97005",
"shipiumOriginId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"
},
"requestDateOverride": null,
"shipDateOverride": null,
"options": {
"shippingOptions": {
"fromCountryCode": "US",
"fromPostalCode": "97005"
}
}
}
Example: Ship From Origin Override
curl --request POST \
--url <<api_url>>/api/v1/deliveryexperience/productview \
--header 'accept: application/json' \
--header $AUTHSTRING \
--header 'content-type: application/json' \
--data '{"customerCountryCode": "US",
"customerPostalCode": "42701","options": {"shippingOptions": {"originId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"}}}'
Here is the JSON body expanded:
{
"customerCountryCode": "US",
"customerPostalCode": "42701",
"options": {
"shippingOptions": {
"originId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"
}
}
}
This example shows the response when extra options are used:
{
"deliveryEstimateId": "9ea1a221-d2ff-4773-93a5-d3314d12fbf3",
"requestDate": "2022-05-31T21:00:28.413Z",
"shipEstimateDate": "2022-06-01T20:00:00-04:00",
"deliveryEstimateDate": "2022-06-04T20:00:00-04:00",
"estimatedTimeInTransitDays": 3,
"customerCountryCode": "US",
"customerPostalCode": "42701",
"shippingOrigin": {
"countryCode": "US",
"postalCode": "97005",
"shipiumOriginId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"
},
"requestDateOverride": null,
"shipDateOverride": null,
"options": {
"shippingOptions": {
"originId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"
}
}
}
Retrieving information about a prior call
If you need to retrieve the response from a prior POST, use the deliveryEstimateId
that was returned in the response. While this is a rare use case, it can be used for certain page refresh cases.
curl --request GET \
--url <<api_url>>/api/v1/deliveryexperience/productview/0b3d140a-525b-43a7-896c-cdc381580d61 \
--header 'accept: application/json' \
--header $AUTHSTRING \
This call returns exactly the same content as returned in the response for the original productview
POST.
More information on the API responses
As with all Shipium API responses, this API follows the API Response Codes standards unless otherwise specified.
Updated 29 days ago