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 optional components for certain client installations, two are critical to include in every API call:

customerCountryCode, and
customerPostalCode.

These allow Shipium to return a Customer Delivery Estimate that is specific to your customer.

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.

🔐

Authenticating for Curl

Open Recipe

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 Fulfillment Center location using a fromCountryCode and fromPostalCode pair and replacing the default shipOption that was shown to the customer with "TwoDay". The default shipOption is the standard service level.

🚧
Be cautious overriding the ship option
Overriding the shipOption default value of STANDARD implies that you want to explicitly dictate how many in-transit days the shipping method will take. Shipium recommends not using this override option unless you want to control the in-transit shipping days.

This example shows the response when extra options are used:

{
    "deliveryEstimateId": "d64cc12d-9349-4e78-acd5-32dce3c35805",
    "requestDate": "2023-06-08T15:53:07.81Z",
    "shipEstimateDate": "2023-06-09T20:00:00-04:00",
    "deliveryEstimateDate": "2023-06-11T20:00:00-04:00",
    "estimatedTimeInTransitDays": 2,
    "customerCountryCode": "US",
    "customerPostalCode": "98101",
    "shippingOrigin": {
        "countryCode": "US",
        "postalCode": "63376",
        "shipiumOriginId": "cd39073b-3d07-45d4-95d6-0afe7e9c46d1"
    },
    "requestDateOverride": null,
    "shipDateOverride": null,
    "options": {
        "shippingOptions": {
            "shipOption": "TwoDay",
            "fromCountryCode": "US",
            "fromPostalCode": "63376"
        }
    }
}

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 thatshipDateOverride must always be greater than requestDateOverride if it is being used or later than now 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.