Get started

To use the Cart Checkout Delivery Promise API, you must first configure your account. Guidance can be found in the Delivery Promise documentation. This document provides instructions for using the API.

Retrieve an estimated delivery date (EDD) for your cart checkout pages with the Cart Checkout Delivery Promise API

The Shipium Cart Checkout Delivery Promise API is designed to be flexible to fit your organization’s business strategy and technical capabilities. All API calls assume you're using one of the authentication mechanisms detailed in our authentication documentation. The endpoint for all Cart Checkout Delivery Promise API calls is included in the table below.

API type	API endpoint
POST	https://api.shipium.com/api/v1/deliveryexperience/cartDeliveryEstimate

📘
Authentication for API Calls
In the cURL example 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

The following table provides all required and optional fields for calling the Cart Checkout Delivery Promise API. You can find additional support in the Cart Delivery Date Estimate API Reference.

Request field	Required/Optional	Field properties	Description
`partnerCartId`	Required	String	A unique identifier for this request
`customerCountryCode`	Required	String enumeration Limited to 2 characters and ISO 3166 standards	Shipment’s destination country
`customerPostalCode`	Required	String	Shipment's destination country appropriate postal code
`requestDateOverride`	Optional	String enumeration Limited to the ISO-8601 standard Ex: `2019-10-31T00:00:00Z`	Dictate the base calculation of when the request happened. This field allows you to specify the request as though it had happened on a different date and/or time.
`shipDateOverride`	Optional	String Either the ISO-8601 standard date or a local date (yyyy-mm-dd)	Dictate the date that the origin will ship the item.
`productViewDelivery EstimateIds`	Optional	String Ex. `0b3d140a-525b-43a7-896c-cdc381580d61`	An array of identifiers that were returned in the response from a call to the Product View API
`cartShippingOptions .shippingLocationOptions`	Optional	Array	An array of possible shipping locations with available inventory; either the `fromCountryCode` and `fromPostalCode` or the `originId` can be provided.
`cartShippingOptions .shippingLocationOptions .shipOption`	Optional	String enumeration Limited to available ship options: - `standard` - `same_day` - `next_day` - `two_day` - `three_day`	Retrieve the estimate for a different ship option; the default value is `standard`.
`cartShippingOptions .shippingLocationOptions .fromCountryCode`	Conditional	String Limited to 2 characters and ISO 3166 standards	Shipment's origin country; either the `fromCountryCode` and `fromPostalCode` or the `originId` must be provided.
`cartShippingOptions .shippingLocationOptions .fromPostalCode`	Conditional	String	Shipment's origin country appropriate postal code; either the `fromCountryCode` and `fromPostalCode` or the `originId` must be provided.
`cartShippingOptions .shippingLocationOptions .originId`	Conditional	String Ex.: `origin-id-123`	A unique identifier for the origin, whether one your organization assigned (partnerProvided) or a Shipium ID; either the `fromCountryCode` and `fromPostalCode` or the `originId` must be provided. An example of a shipping override using an `originId` is provided below.
`cartShippingOptions .shippingLocationOptions .estimateSource`	Optional	String enumeration Values are: - `ShipiumCalculated` - `PartnerProvided` - `CarrierProvided` - `Unknown`	The source used to generate the estimate
`referenceIdentifiers.name`	Optional	String No character limitations	Optionally include your organization's own identifier to be associated with the shipment for internal tracking.
`referenceIdentifiers.value`	Optional	String Limited to numeric characters	Optionally include your organization's own identifier to be associated with the shipment for internal tracking.

The Cart Checkout Delivery Promise response attributes are defined in the following table.

Response attribute	Description
`shipiumCartId`	Unique Shipium-generated ID related to the request and response
`deliveryEstimateId`	Unique Shipium-generated ID related to the response
`shipEstimateDate`	A valid date in ISO 8601 format representing the estimated ship date to a customer configured in the call parameters (e.g., 2023-10-31T00:00:00Z)
`shipEstimateDateUTC`	A valid date in ISO 8601 format with UTC timezone representing the estimated ship date to a customer configured in the call parameters (e.g., 2023-10-31T00:00:00Z)
`deliveryEstimateDate`	Shipium's estimated delivery date (EDD) in the local timezone of the delivery postal code (`customerPostalCode`)
`deliveryEstimateDateUTC`	A valid date in ISO 8601 format with UTC timezone representing the estimated delivery date to a customer configured in the call parameters (e.g., 2023-10-31T00:00:00Z)
`estimateSource`	The time in transit (TNT) calculation method that was used when calculating this EDD
`estimatedTimeInTransitDays`	An integer value of the time in transit (TNT) in days

Shipium assumptions for the Cart Checkout Delivery Promise API

Origin
The shipment will ship from the closest origin to the customer based on distance.
Shipment date
The shipment will ship based on the timestamp of the request plus the configured click-to-ship time and the configured schedule at the origin.
Ship method
Standard Ground

Retrieve an EDD for a shipment at cart checkout (primary use case)

Example cURL call

curl --request POST   
  --url <<api_url>>/api/v1/deliveryexperience/cartDeliveryEstimate 
  --header 'accept: application/json' 
  --header $AUTHSTRING  
  --header 'content-type: application/json'  
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

{
  "partnerCartId": "74b6e652-8db2-4441-9cf6-85a18a15ca88",
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "productViewDeliveryEstimateIds": ["0b3d140a-525b-43a7-896c-cdc381580d61"],
  "cartShippingOptions": {
    "shippingLocationOptions": [
      {
        "fromCountryCode": "US",
        "fromPostalCode": "98101",
        "estimateSource": "ShipiumGenerated"
      }
      ]
    },
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
  ]
}

Example response

{
   "shipiumCartId": "66401470-aedc-4a03-9509-a8383e650a4d",    
   "partnerCartId": "74b6e652-8db2-4441-9cf6-85a18a15ca88",   
   "customerCountryCode": "US",                               
   "customerPostalCode": "98101",                                    
   "productViewDeliveryEstimateIds": ["0b3d140a-525b-43a7-896c-cdc381580d61"],     
   "originDeliveryEstimates":[
      {
         "deliveryEstimateId": "0b3d140a-525b-43a7-896c-cdc381580d61",
         "deliveryEstimateDate": "2019-10-31T00:00:00Z",     
         "deliveryEstimateDateUTC": "2019-10-31T00:00:00Z",    
         "estimateSource": "ShipiumGenerated",                 
         "estimatedTimeInTransitDays": 3,                     
         "shippingOrigin": {                                   
            "countryCode": "US",
            "postalCode": "98101",
            "shipiumOriginId": "0b3d140a-525b-43a7-896c-cdc381580d62",
            "originProcessingDays": 2.5
         },
         "cartShippingOptions":{
            "shippingLocation": {
               "fromCountryCode": "US",
               "fromPostalCode": "98101",
               "estimateSource": "ShipiumGenerated"
            }
         }
      }
   ],
   "referenceIdentifiers": [                                   
            {
         "name": "MY_KEY",
         "value": "MY_VALUE"
      }
   ]
}

Augmentations to the EDD request (additional use cases)

Your organization may choose to augment your EDD request by including any of the following optional fields, which will generally enhance the accuracy of our EDD calculation.

Request date override

requestDateOverride

Dictate the base calculation of when the request happened. This field allows you to specify the request as though it had happened on a different date and/or time.

Example cURL call

curl --request POST   
  --url <<api_url>>/api/v1/deliveryexperience/cartDeliveryEstimate 
  --header 'accept: application/json' 
  --header $AUTHSTRING  
  --header 'content-type: application/json'  
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

{
  "partnerCartId": "74b6e652-8db2-4441-9cf6-85a18a15ca88",
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "requestDateOverride": "2019-10-31T00:00:00Z",
  "productViewDeliveryEstimateIds": ["0b3d140a-525b-43a7-896c-cdc381580d61"],
  "cartShippingOptions": {
    "shippingLocationOptions": [
      {
        "fromCountryCode": "US",
        "fromPostalCode": "98101",
        "estimateSource": "ShipiumGenerated"
      }
      ]
    },
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
  ]
}

Example response

{
   "shipiumCartId": "66401470-aedc-4a03-9509-a8383e650a4d",    
   "partnerCartId": "74b6e652-8db2-4441-9cf6-85a18a15ca88",   
   "customerCountryCode": "US",                               
   "customerPostalCode": "98101", 
   "requestDateOverride": "2019-10-31T00:00:00Z",
   "productViewDeliveryEstimateIds": ["0b3d140a-525b-43a7-896c-cdc381580d61"],     
   "originDeliveryEstimates":[
      {
         "deliveryEstimateId": "0b3d140a-525b-43a7-896c-cdc381580d61",
         "deliveryEstimateDate": "2019-10-31T00:00:00Z",     
         "deliveryEstimateDateUTC": "2019-10-31T00:00:00Z",    
         "estimateSource": "ShipiumGenerated",                 
         "estimatedTimeInTransitDays": 3,                     
         "shippingOrigin": {                                   
            "countryCode": "US",
            "postalCode": "98101",
            "shipiumOriginId": "0b3d140a-525b-43a7-896c-cdc381580d62",
            "originProcessingDays": 2.5
         },
         "cartShippingOptions":{
            "shippingLocation": {      
               "fromCountryCode": "US",
               "fromPostalCode": "98101",
               "estimateSource": "ShipiumGenerated"
            }
         }
      }
   ],
   "referenceIdentifiers": [                                   
            {
         "name": "MY_KEY",
         "value": "MY_VALUE"
      }
   ]
}

Shipping origin override

shippingOrigin

Dictate the origin that will fulfill the shipment by using the originID. You can retrieve the originID value from the Shipium platform, following these steps (your Implementation team member will assist you):

Access your organization's account by logging in to the Shipium Console.
Navigate to Configure in the lefthand menu, and then select Fulfillment Configuration.

Within Fulfillment Center Configuration, select Origins.

From your list of origins, locate the one for which you wish to retrieve the originID. Then choose Detail from the Actions dropdown menu for that origin.
Copy the value listed for the Origin ID in the detailed card view. This is your originID value.

Example cURL call

curl --request POST   
  --url <<api_url>>/api/v1/deliveryexperience/cartDeliveryEstimate 
  --header 'accept: application/json' 
  --header $AUTHSTRING  
  --header 'content-type: application/json'  
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body by origin ID

{
  "partnerCartId": "74b6e652-8db2-4441-9cf6-85a18a15ca88",
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "productViewDeliveryEstimateIds": ["0b3d140a-525b-43a7-896c-cdc381580d61"],
  "cartShippingOptions": {
    "shippingLocationOptions": [
      {
        "fromCountryCode": "US",
        "fromPostalCode": "98101",
        "originId": "origin-id-123",
        "estimateSource": "ShipiumGenerated"
      }
      ]
    },
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
  ]
}

Example response by origin ID

{
   "shipiumCartId": "66401470-aedc-4a03-9509-a8383e650a4d",    
   "partnerCartId": "74b6e652-8db2-4441-9cf6-85a18a15ca88",   
   "customerCountryCode": "US",                               
   "customerPostalCode": "98101",                                    
   "productViewDeliveryEstimateIds": ["0b3d140a-525b-43a7-896c-cdc381580d61"],     
   "originDeliveryEstimates":[
      {
         "deliveryEstimateId": "0b3d140a-525b-43a7-896c-cdc381580d61",
         "deliveryEstimateDate": "2019-10-31T00:00:00Z",     
         "deliveryEstimateDateUTC": "2019-10-31T00:00:00Z",    
         "estimateSource": "ShipiumGenerated",                 
         "estimatedTimeInTransitDays": 3,                     
         "shippingOrigin": {                                   
            "countryCode": "US",
            "postalCode": "98101",
            "shipiumOriginId": "0b3d140a-525b-43a7-896c-cdc381580d62",
            "originProcessingDays": 2.5
         },
         "cartShippingOptions":{
            "shippingLocation": {
               "fromCountryCode": "US",
               "fromPostalCode": "98101",
               "originId": "origin-id-123",
               "estimateSource": "ShipiumGenerated"
            }
         }
      }
   ],
   "referenceIdentifiers": [                                   
            {
         "name": "MY_KEY",
         "value": "MY_VALUE"
      }
   ]
}

Ship date override

shipDateOverride

Dictate the date that the origin will ship the item.

Example cURL call

curl --request POST   
  --url <<api_url>>/api/v1/deliveryexperience/cartDeliveryEstimate 
  --header 'accept: application/json' 
  --header $AUTHSTRING  
  --header 'content-type: application/json'  
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

{
  "partnerCartId": "74b6e652-8db2-4441-9cf6-85a18a15ca88",
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "shipDateOverride": "2019-10-31T00:00:00.000000Z",
  "productViewDeliveryEstimateIds": ["0b3d140a-525b-43a7-896c-cdc381580d61"],
  "cartShippingOptions": {
    "shippingLocationOptions": [
      {
        "fromCountryCode": "US",
        "fromPostalCode": "98101",
        "estimateSource": "ShipiumGenerated"
      }
      ]
    },
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
  ]
}

Example response

{
   "shipiumCartId": "66401470-aedc-4a03-9509-a8383e650a4d",    
   "partnerCartId": "74b6e652-8db2-4441-9cf6-85a18a15ca88",   
   "customerCountryCode": "US",                               
   "customerPostalCode": "98101", 
   "shipDateOverride": "2019-10-31T00:00:00.000000Z",
   "productViewDeliveryEstimateIds": ["0b3d140a-525b-43a7-896c-cdc381580d61"],     
   "originDeliveryEstimates":[
      {
         "deliveryEstimateId": "0b3d140a-525b-43a7-896c-cdc381580d61",
         "deliveryEstimateDate": "2019-10-31T00:00:00Z",     
         "deliveryEstimateDateUTC": "2019-10-31T00:00:00Z",    
         "estimateSource": "ShipiumGenerated",                 
         "estimatedTimeInTransitDays": 3,                     
         "shippingOrigin": {                                   
            "countryCode": "US",
            "postalCode": "98101",
            "shipiumOriginId": "0b3d140a-525b-43a7-896c-cdc381580d62",
            "originProcessingDays": 2.5
         },
         "cartShippingOptions":{
            "shippingLocation": {
               "fromCountryCode": "US",
               "fromPostalCode": "98101",
               "estimateSource": "ShipiumGenerated"
            }
         }
      }
   ],
   "referenceIdentifiers": [                                   
            {
         "name": "MY_KEY",
         "value": "MY_VALUE"
      }
   ]
}

Ship option override

shipOption

Retrieve the estimate for a different ship option.

Available ship options for the API call request:

Standard
SameDay
NextDay
TwoDay
ThreeDay

Example cURL call

curl --request POST   
  --url <<api_url>>/api/v1/deliveryexperience/cartDeliveryEstimate 
  --header 'accept: application/json' 
  --header $AUTHSTRING  
  --header 'content-type: application/json'  
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

{
  "partnerCartId": "74b6e652-8db2-4441-9cf6-85a18a15ca88",
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "productViewDeliveryEstimateIds": ["0b3d140a-525b-43a7-896c-cdc381580d61"],
  "cartShippingOptions": {
    "shippingLocationOptions": [
      {
        "shipOption": "SameDay",
        "fromCountryCode": "US",
        "fromPostalCode": "98101",
        "estimateSource": "ShipiumGenerated"
      }
      ]
    },
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
  ]
}

Example response

{
   "shipiumCartId": "66401470-aedc-4a03-9509-a8383e650a4d",    
   "partnerCartId": "74b6e652-8db2-4441-9cf6-85a18a15ca88",   
   "customerCountryCode": "US",                               
   "customerPostalCode": "98101",                                    
   "productViewDeliveryEstimateIds": ["0b3d140a-525b-43a7-896c-cdc381580d61"],     
   "originDeliveryEstimates":[
      {
         "deliveryEstimateId": "0b3d140a-525b-43a7-896c-cdc381580d61",
         "deliveryEstimateDate": "2019-10-31T00:00:00Z",     
         "deliveryEstimateDateUTC": "2019-10-31T00:00:00Z",    
         "estimateSource": "ShipiumGenerated",                 
         "estimatedTimeInTransitDays": 3,                     
         "shippingOrigin": {                                   
            "countryCode": "US",
            "postalCode": "98101",
            "shipiumOriginId": "0b3d140a-525b-43a7-896c-cdc381580d62",
            "originProcessingDays": 2.5
         },
         "cartShippingOptions":{
            "shippingLocation": {
              "shipOption": "SameDay", 
              "fromCountryCode": "US",
              "fromPostalCode": "98101",
              "estimateSource": "ShipiumGenerated"
            }
         }
      }
   ],
   "referenceIdentifiers": [                                   
            {
         "name": "MY_KEY",
         "value": "MY_VALUE"
      }
   ]
}

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

Get started

Retrieve an estimated delivery date (EDD) for your cart checkout pages with the Cart Checkout Delivery Promise API

📘Authentication for API Calls

Shipium assumptions for the Cart Checkout Delivery Promise API

Retrieve an EDD for a shipment at cart checkout (primary use case)

Example cURL call

Example request body

Example response

Augmentations to the EDD request (additional use cases)

Request date override

Example cURL call

Example request body

Example response

Shipping origin override

Example cURL call

Example request body by origin ID

Example response by origin ID

Ship date override

Example cURL call

Example request body

Example response

Ship option override

Example cURL call

Example request body

Example response

Resources

📘
Authentication for API Calls