Product View (Delivery Estimate-Based)

Overview

Use the /deliveryexperience/productview API to:

  • report when a product page has been shown to a Customer, and to
  • retrieve a Customer Delivery Estimate to show them.

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

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, the critical ones are customerCountryCode, customerPostalCode and productId. These allow us to return a Customer Delivery Estimate that is specific to your customer and the specific product viewed.

API call and response examples are shown below.

❗️

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 /deliveryexperience/productview 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 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.


Did this page help you?