Guides

Subscription Timing API

Determine when subscription shipments should be shipped with Shipium's Subscription Timing API.

Suggest Edits

Get started

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

Retrieve subscription timing guidance from the Subscription Timing API

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

API typeAPI endpoint
POSThttps://api.shipium.com/api/v1/subscription/timing

The following table provides all required and optional field descriptions for calling the Subscription Timing API. You can find additional support in the Subscription Timing API Reference.

Request fieldRequired/OptionalField propertiesDescription
customerCountryCodeRequiredString enumeration
Limited to 2 characters and ISO 3166 standards		Shipment’s destination country
customerPostalCodeRequiredString
Limited to valid USPS postal ZIP codes 		Shipment's destination postal code
desiredDeliveryDateRequiredString date
Limited to the ISO-8601 standard OR a date only in YYYY-MM-DD format.		The date on which you want the shipment in question to be delivered on or before.
Note that this value should be in the timezone of the delivery postal code. If you provide only date, that will be assumed.
requestDateOverrideOptionalString date
Limited to the ISO-8601 standard 		Overrides the request date to a specific date and time from which the ship-by and drop-by date are calculated
options.shippingOptions .fromCountryCodeOptional, but must be paired with fromPostalCodeString enumeration
2-character ISO 3166 standards country code		Dictate the origin that will fulfill the shipment by using the country code and postal code.
options.shippingOptions .fromPostalCodeOptional, but must be paired with fromCountryCodeString enumeration Valid USPS postal ZIP code valueDictate the origin that will fulfill the shipment by using the country code and postal code.
options.shippingOptions .originIdOptionalString enumeration
Shipium-generated originID value for the particular origin		Dictate the origin that will fulfill the shipment by using the origin ID.
options.shippingOptions .shipOptionOptionalString enumeration
One of the valid values for shipOption, listed below.		Dictate the ship option that will be used and thus the likely ship time available for the shipment, if needed.
partnerReferenceIdentifierOptionalString
No character limitations		An optional reference identifier your organization can provide to use for reporting purposes
referenceIdentifierOptionalString
No character limitations		An optional identifier you can provide to reference the shipment
referenceIdentifiers.nameOptionalString
No character limitations		Optionally include your organization's own identifier to be associated with the shipment for internal tracking.
referenceIdentifiers.valueOptionalString
No character limitations		Optionally include your organization's own value to be associated with the specified name, associated with this shipment for internal tracking.

The primary elements of the response (other than the request elements) are listed in this table. The primary pieces of data returned are the fcDropDate and the shipByDate, representing when a shipment should be sent to the fulfillment center (FC) and when it should be shipped, respectively, in order to get it to the customer by the requested desiredDeliveryDate.

Response attributeDescription
subscriptionTimingIdUnique Shipium-generated ID associated with the request and response
fcDropByDateThe date by which the fulfillment center (FC) should begin processing of the shipment in order to hit the desired delivery date that was requested. This value is calculated based on the shipByDate and a calculation using the FC processing time configured for the appropriate origin.
shipByDateThe date by which the FC should ship the shipment in order to hit the desired delivery date that was requested.
estimateSourceThe source of the times in transit (TNTs) that were utilized as part of the calculation. This will be one of ShipiumCalculated, PartnerProvided, or CarrierProvided.
estimatedTransitDaysThe number of transit days between the desired delivery date and the estimated ship by date
shippingOrigin .originProcessingDaysThe number of days a shipment takes to process at the origin before being shipped; this can be a decimal value to represent fractional days.

In addition to these primary elements of the response, if the desired delivery date provided in the request would require a ship date in the past, the shipDateExceptions attributes in the following table will be returned in the response.

Response attributeDescription
shipDateExceptions.exceptionTypeThe type of exception for the ship date calculation exception
shipDateExceptions.exceptionDescriptionA description of the type of exception for the ship date calculation exception
shipDateExceptions.effectiveShipByDateProvides an effective ship-by date in the local timezone of the origin

When the Subscription Timing service initially thinks a shipment should have already been shipped and provides an estimated ship date that is in the past, Shipium adjusts the ship date by selecting the earliest configured shipping cutoff time for the origin (fulfillment center, FC) from which the package is being shipped. For example, if a request was made at 2024-06-13T19:23:12-06:00 and the cutoff time for the FC was 14:00, the resulting exception ship date would be 2024-06-14T14:00:00-06:00.

Basic subscription timing request and response

Example cURL call

This example shows a typical Subscription Timing API call cURL request: 

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

Example request body

This is an example JSON request:

{
  "customerCountryCode": "US",
  "customerPostalCode": "98103",
  "desiredDeliveryDate": "2021-11-20",
  "requestDateOverride": "2021-11-15T00:00:01-07:00",
  "options": {
  	"shippingOptions": {
    	"fromCountryCode": "US",
    	"fromPostalCode": "98101",
    	"originId": "origin-id-123",
    	"shipOption": "standard"
  }
},
"partnerReferenceIdentifier": "subscriptionA1",  
"referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
    ]
}

Example response body

{
    "subscriptionTimingId": "8ffa82ab-e67a-4b9f-bed6-d3b29b088bb1",
    "customerCountryCode": "US",
    "customerPostalCode": "98103",
    "shippingOrigin": {
        "countryCode": "US",
        "postalCode": "98101",
        "shipiumOriginId": "d1135cd9-3f8b-4a54-b8cb-573f0ab6870d",
        "originProcessingDays": 1.0
    },
    "options": {
        "shippingOptions": {
            "fromCountryCode": "US",
            "fromPostalCode": "98101",
            "originId": "origin-id-123",
            "shipOption": "standard"
        }
    },
    "desiredDeliveryDate": "2021-11-20T00:00:00Z",
    "requestDateOverride": "2021-11-15T00:00:01-07:00",
    "shipByDate": "2021-11-17T22:00:00-07:00",
    "fcDropByDate": "2021-11-16T00:00:01-07:00",
    "estimateSource": "ShipiumCalculated",
    "estimatedTransitDays": 3,
    "partnerReferenceIdentifier": "subscriptionA1",
    "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
    "referenceIdentifiers": [
        {
            "name": "MY_KEY",
            "value": "MY_VALUE"
        }
    ]
}

Example response body with a ship date exception

{
  "subscriptionTimingId": "8ffa82ab-e67a-4b9f-bed6-d3b29b088bb1",
  "customerCountryCode": "US",
  "customerPostalCode": "98103",
  "shippingOrigin": {
      "countryCode": "US",
      "postalCode": "98101",
      "shipiumOriginId": "d1135cd9-3f8b-4a54-b8cb-573f0ab6870d",
      "originProcessingDays": 1.0
  },
  "desiredDeliveryDate": "2021-11-20T00:00:00Z",
  "requestDateOverride": "2021-11-15T00:00:01-07:00",
  "shipByDate": "2021-11-17T22:00:00-07:00",
  "fcDropByDate": "2021-11-16T00:00:01-07:00",
  "estimateSource": "ShipiumCalculated",
  "estimatedTransitDays": 3,
  "shipDateExceptions": [
        {
            "exceptionType": "ShipDateInPast",
            "exceptionDescription": "The desiredDeliveryDate requires a shipDate that is in the past.",
            "effectiveShipByDate": "2021-11-15T11:09:52.071939792-07:00"
        }
    ],
  "partnerReferenceIdentifier": "subscriptionA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
    ]
}

Advanced subscription timing request and response

Many users of the Subscription Timing API may need to pass additional details, such as:

  • the expected fulfillment center from which the shipment will be sent; or
  • details of a ship option other than "standard".

Example cURL request

This example shows an advanced Subscription Timing API call cURL request:

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

Example request body

Note that the referenceIdentifiers section is not required, but may be helpful for tagging certain requests for debugging purposes later.

{
  "customerCountryCode": "US", 
  "customerPostalCode": "98103", 
  "desiredDeliveryDate": "2021-11-20",
  "requestDateOverride": "2021-11-15T00:00:01-07:00", 
  "options": {
    "shippingOptions": {
      "fromCountryCode": "US",
      "fromPostalCode": "98101",
      "shipOption": "standard"
  }
},
  "partnerReferenceIdentifier": "subscriptionA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
    ]
}

Example response body

{
  "customerCountryCode": "US",
  "customerPostalCode": "98103",
  "desiredDeliveryDate": "2021-11-20T00:00:00Z",
  "requestDateOverride": "2021-11-15T00:00:01-07:00",
  "shipByDate": "2021-11-17T22:00:00-07:00",
  "fcDropByDate": "2021-11-16T00:00:01-07:00",
  "shippingOrigin": {
    "countryCode": "US",
    "postalCode": "98101",
    "shipiumOriginId": "d1135cd9-3f8b-4a54-b8cb-573f0ab6870d",
    "originProcessingDays": 1.0
  },
  "options": {
      "shippingOptions": {
      "fromCountryCode": "US", 
      "fromPostalCode": "98101", 
      "shipOption": "standard"
      }
  },
  "estimateSource": "ShipiumCalculated",
  "estimatedTransitDays": 3,
  "subscriptionTimingId": "b903b8b0-84b4-11ea-ab12-0800200c9a66",
  "partnerReferenceIdentifier": "subscriptionA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
    ]
}

Call and response with advanced options

In some situations, your organization may need to pass additional shipping options due to specialized fulfillment information. These cases are more complex, so you should consider carefully before using them in your integration.

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

Example request body

Here is the JSON request body expanded:

{
    "customerCountryCode": "US",
    "customerPostalCode": "98103",
    "desiredDeliveryDate": "2021-11-20",
    "requestDateOverride": "2021-11-15T00:00:01-07:00",
    "options": {
      "shippingOptions": {
        "shipOption": "NextDay"
  }
},
  "partnerReferenceIdentifier": "subscriptionA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
    ]
}

Example response body when extra options are used

{
  "subscriptionTimingId": "169b7732-5e6d-4a91-90f8-9fc98439f1aa",
  "customerCountryCode": "US",
  "customerPostalCode": "98103",
  "shippingOrigin": {
      "countryCode": "US",
      "postalCode": "98101",
      "shipiumOriginId": "3adcd9f9-06de-4620-894f-7b1e6db1a815",
      "originProcessingDays": 1.0
  },
  "options": {
      "shippingOptions": {
          "shipOption": "NextDay"
      }
  },
  "desiredDeliveryDate": "2021-11-20T00:00:00Z",
  "requestDateOverride": "2021-11-15T00:00:01-07:00",
  "shipByDate": "2021-11-18T22:00:00-08:00",
  "fcDropByDate": "2021-11-17T00:00:01-08:00",
  "estimateSource": "ShipiumCalculated",
  "estimatedTransitDays": 3,
  "partnerReferenceIdentifier": "subscriptionA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
    ]
}

Ship from origin postal code override

Example cURL request

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

Example request body

Here is the JSON request body expanded:

{
    "customerCountryCode": "US",
    "customerPostalCode": "98103",
    "desiredDeliveryDate": "2021-11-20T00:00:00.000000Z",
    "requestDateOverride": "2021-11-15T00:00:01-07:00",
    "options": {
      "shippingOptions": {
        "fromCountryCode": "US",
        "fromPostalCode": "98101"
  }
},
  "partnerReferenceIdentifier": "subscriptionA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
    ]
}

Example response body when extra options are used

{
  "subscriptionTimingId": "93740852-b10f-45eb-bbcf-167260d956d7",
  "customerCountryCode": "US",
  "customerPostalCode": "98103",
  "shippingOrigin": {
      "countryCode": "US",
      "postalCode": "98101",
      "shipiumOriginId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce",
      "originProcessingDays": 1.0
  },
  "options": {
      "shippingOptions": {
          "fromCountryCode": "US",
          "fromPostalCode": "97005"
      }
  },
  "desiredDeliveryDate": "2021-11-20T00:00:00Z",
  "requestDateOverride": "2021-11-15T00:00:01-07:00",
  "shipByDate": "2021-11-15T22:00:00-08:00",
  "fcDropByDate": "2021-11-12T00:00:01-08:00",
  "estimateSource": "ShipiumCalculated",
  "estimatedTransitDays": 3,
  "partnerReferenceIdentifier": "subscriptionA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
    ]
}

Ship from origin override

Example cURL request

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

Example request body

Here is the request body JSON expanded:

{
    "customerCountryCode": "US",
    "customerPostalCode": "98103",
    "desiredDeliveryDate": "2021-11-20T00:00:00.000000Z",
    "requestDateOverride": "2021-11-15T00:00:01-07:00",
    "options": {
        "shippingOptions": {
            "originId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"
        }
    },
  "partnerReferenceIdentifier": "subscriptionA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866", 
  "referenceIdentifiers": [
      {
        "name": "MY_KEY",
        "value": "MY_VALUE"
      }
      ]
}

Example response body when the shipping origin is provided

{
  "subscriptionTimingId": "a3be42a0-ab6b-47fa-a5f1-c720143e70f7",
  "customerCountryCode": "US",
  "customerPostalCode": "98103",
  "options": {
      "shippingOptions": {
          "originId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"
      }
  },
  "shippingOrigin": {
      "countryCode": "US",
      "postalCode": "98101",
      "shipiumOriginId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce",
      "originProcessingDays": 1.0
  },
  "desiredDeliveryDate": "2021-11-20T00:00:00Z",
  "requestDateOverride": "2021-11-15T00:00:01-07:00",
  "shipByDate": "2021-11-16T22:00:00-08:00",
  "fcDropByDate": "2021-11-15T00:00:01-08:00",
  "estimateSource": "ShipiumCalculated",
  "estimatedTransitDays": 3,
  "partnerReferenceIdentifier": "subscriptionA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
    ]
}

📘

More information on the API responses

As with all Shipium API responses, this API follows the API Response Codes standards unless otherwise specified.

Resources

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

Updated 5 days ago

What’s Next