About Delivery Promise

Delivery Promise provides Shipium’s best estimate of a shipment's delivery date, which we call estimated delivery date, or EDD. You can read more about Delivery Promise on our website.

This guide provides Shipium’s recommended steps for using Delivery Promise, both setting up your organization’s account and using the Delivery Promise application programming interface (API) to retrieve a shipment’s EDD.

Set up Delivery Promise for your organization

To start using Delivery Promise, you’ll need to complete the following steps. Your dedicated Shipium Implementation team member will assist you with each one.

Set up your Shipium account
You’ll set up your organization’s account within the Shipium platform.
Configure your fulfillment network
All warehouse or store origins and origin schedules are set up on the Shipium platform and configured to your organization's exact network properties.
Configure your time in transit (TNT) calculation hierarchy and upload shipment data
TNTs are needed for the most accurate EDD. You'll set up your preferred TNT structure and upload your organization’s historical shipment values. Generally, Shipium requests that you upload 12 months of data.

Retrieve an estimated delivery date (EDD)

The Shipium 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 Delivery Promise API calls is included in the table below.

API type	API endpoint
POST	/api/v1/deliveryexperience/productview

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

Request field	Required/Optional	Field properties	Description
`customerCountryCode`	Required	string enumeration Limited to 2 characters and ISO 3166 standards	Shipment’s destination country
`customerPostalCode`	Required	string Limited to valid USPS postal ZIP codes	Shipment's destination postal code
`requestDateOverride`	Optional	string enumeration Limited to the ISO-8601 standard	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.
`shippingOrigin`	Optional	string enumeration Limited to the Shipium-generated originID value for the particular origin	Dictate the origin that will fulfill the shipment by using the originID.
`shipDateOverride`	Optional	string enumeration Limited to the ISO-8601 standard	Dictate the date that the origin will ship the item.
`shipOption`	Optional	string enumeration Limited to available ship options: - same_day - next_day - two_day - three_day	Retrieve the estimate for a different ship option.
`reference.identifiers.name`	Optional	string No character limitations	Optionally include your organization's own identifier to be associated with the shipment for internal tracking.
`reference.identifiers.value`	Optional	string Limited to numeric characters	Optionally include your organization's own identifier to be associated with the shipment for internal tracking.

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

Response attribute	Description
`deliveryEstimateId`	Unique Shipium-generated ID related to the response
`deliveryEstimateDate`	Shipium's estimated delivery date (EDD) in the local timezone of the delivery postal code (`customerPostalCode`)
`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 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 (primary use case)

Example cURL call

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

Example request body

{
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "referenceIdentifiers": [
    {
      "name": "string",
      "value": "string"
    }
  ],
}

Example response

{
  "deliveryEstimateId": "a2e3281f-42db-4afb-be48-ad1246117400",
  "requestDate": "2023-06-15T18:25:37.01Z",
  "shipEstimateDate": "2023-06-16T20:00:00-04:00",
  "deliveryEstimateDate": "2023-06-20T20:00:00-04:00",
  "estimatedTimeInTransitDays": 4,
  "estimateSource": "ShipiumCalculated",
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "shippingOrigin": {
      "countryCode": "US",
      "postalCode": "42718",
      "shipiumOriginId": "194d28d5-53b3-4c80-badc-0793ba220932"
  },
  "requestDateOverride": "null",
  "shipDateOverride": "null",
  "referenceIdentifiers": [
    {
      "name": "string",
      "value": "string"
    }
    ]
}

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/productview 
  --header 'accept: application/json' 
  --header $AUTHSTRING  
  --header 'content-type: application/json'  
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

{
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "requestDateOverride": "2023-07-03T20:00:00-04:00",
  "referenceIdentifiers": [
    {
      "name": "string",
      "value": "string"
    }
    ]
}

Example response

{
  "deliveryEstimateId": "a2e3281f-42db-4afb-be48-ad1246117400",
  "requestDate": "2023-07-04T00:00:00Z",
  "shipEstimateDate": "2023-07-06T20:00:00-04:00",
  "deliveryEstimateDate": "2023-07-11T20:00:00-04:00",
  "estimatedTimeInTransitDays": 5,
  "estimateSource": "ShipiumCalculated",
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "shippingOrigin": {
      "countryCode": "US",
      "postalCode": "42718",
      "shipiumOriginId": "194d28d5-53b3-4c80-badc-0793ba220932"
  },
  "requestDateOverride": "2023-07-04T00:00:00Z",
  "shipDateOverride": "null",
  "referenceIdentifiers": [
    {
      "name": "string",
      "value": "string"
    }
    ]
}

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 URN in the Audit Properties section of the Detail view. This is your originID value. You may choose to use the Copy icon, but should note that this action copies the "urn:origin:" text preceding the originID.

Example cURL call

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

Example request body by origin ID

{
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "options": {
        "shippingOptions": {
            "originId": "194d28d5-53b3-4c80-badc-0793ba220932"
        }
  },
  "referenceIdentifiers": [
    {
      "name": "string",
      "value": "string"
    }
    ]
}

Example response by origin ID

{
    "deliveryEstimateId": "b0e73539-d3c5-44ec-9e60-fda78a881e7a",
    "requestDate": "2023-06-15T18:32:59.852Z",
    "shipEstimateDate": "2023-06-16T20:00:00-04:00",
    "deliveryEstimateDate": "2023-06-20T20:00:00-04:00",
    "estimatedTimeInTransitDays": 4,
    "estimateSource": "ShipiumCalculated",
    "customerCountryCode": "US",
    "customerPostalCode": "98101",
    "shippingOrigin": {
        "countryCode": "US",
        "postalCode": "42718",
        "shipiumOriginId": "194d28d5-53b3-4c80-badc-0793ba220932"
    },
    "requestDateOverride": null,
    "shipDateOverride": null,
    "options": {
        "shippingOptions": {
            "originId": "194d28d5-53b3-4c80-badc-0793ba220932"
        }
    },
    "referenceIdentifiers": [
      {
        "name": "string",
        "value": "string"
      }
      ]
}

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/productview 
  --header 'accept: application/json' 
  --header $AUTHSTRING  
  --header 'content-type: application/json'  
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

{
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "shipDateOverride": "2023-07-03T20:00:00-04:00",
  "referenceIdentifiers": [
    {
      "name": "string",
      "value": "string"
    }
    ]
}

Example response

{
    "deliveryEstimateId": "a2e3281f-42db-4afb-be48-ad1246117400",
    "requestDate": "2023-06-15T18:27:42.855Z",
    "shipEstimateDate": "2023-07-04T20:00:00-04:00",
    "deliveryEstimateDate": "2023-07-08T20:00:00-04:00",
    "estimatedTimeInTransitDays": 4,
    "estimateSource": "ShipiumCalculated",
    "customerCountryCode": "US",
    "customerPostalCode": "98101",
    "shippingOrigin": {
        "countryCode": "US",
        "postalCode": "42718",
        "shipiumOriginId": "194d28d5-53b3-4c80-badc-0793ba220932"
    },
    "requestDateOverride": null,
    "shipDateOverride": "2023-07-04T00:00:00Z",
    "referenceIdentifiers": [
      {
        "name": "string",
        "value": "string"
      }
      ]
}

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/productview 
  --header 'accept: application/json' 
  --header $AUTHSTRING  
  --header 'content-type: application/json'  
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

{
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "options": {
        "shippingOptions": {
            "shipOption": "TwoDay"
        }
  },
  "referenceIdentifiers": [
    {
      "name": "string",
      "value": "string"
    }
    ]
}

Example response

{
    "deliveryEstimateId": "a2e3281f-42db-4afb-be48-ad1246117400",
    "requestDate": "2023-06-15T18:31:41.941Z",
    "shipEstimateDate": "2023-06-16T20:00:00-04:00",
    "deliveryEstimateDate": "2023-06-18T20:00:00-04:00",
    "estimatedTimeInTransitDays": 2,
    "estimateSource": "ShipiumCalculated",
    "customerCountryCode": "US",
    "customerPostalCode": "98101",
    "shippingOrigin": {
        "countryCode": "US",
        "postalCode": "42718",
        "shipiumOriginId": "194d28d5-53b3-4c80-badc-0793ba220932"
    },
    "requestDateOverride": "null",
    "shipDateOverride": "null",
    "options": {
        "shippingOptions": {
            "shipOption": "TwoDay"
        }
    },
    "referenceIdentifiers": [
      {
        "name": "string",
        "value": "string"
      }
      ]
}

FAQ

Q: Can I include a desired delivery date (DDD) in addition to passing a ship option when using the all-in-one shipment and label method?

A: Yes. For example, shipOption: standard, desiredDeliveryDate: 2023-11-15 limits the carrier selection search to only those methods that are marked as standard and for which the DDD of 2023-11-15 can be met. If the DDD of 2023-11-15 cannot be met, Shipium will return the cheapest service method on 2023-11-16, and so on.

Resources

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