Subscription Timing API Details

Use the Subscription Timing API to determine when subscription shipments should be shipped.

About the Subscription Timing API

Use the Shipium Subscription Timing application programming interface (API) to determine when a given subscription shipment should be shipped out or sent to a warehouse for shipping in order to hit a particular delivery date based on your organization's historical shipping speeds and the location of the address to which the shipment is being sent.

When calling the Subscription Timing API, you pass the desired delivery date, the destination postal code, and the postal code from which you expect the shipment to be sent (e.g., your warehouse's postal code) using the shippingOptions structure.

This document includes details below and walks you through some typical examples. For more technical information, visit the Subscription Timing API Reference.

Set up subscription timing for your organization

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

  1. Set up your Shipium account.
    You’ll set up your organization’s account within the Shipium platform.
  2. 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.
  3. Configure your time in transit (TNT) calculation hierarchy.
    Work with your Shipium contact to determine what hierarchy you want to use for TNTs, between Shipium calculated, your company's preferred overrides (if any), and defaults from the carrier. You can read more about TNT estimations here: Time in Transit Estimations.
  4. Upload shipment data.
    TNTs are needed for the most accurate estimated delivery date, or EDD. You'll set up your preferred TNT structure and upload your organization’s historical shipment values. Shipium requests that you upload 12 months of data. Your Shipium contact will provide the format for this initial file upload and walk you through the process.

Retrieve subscription timing guidance

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.
options.shippingOptions.fromCountryCodeOptional, but must be paired with fromPostalCodestring enumeration 2 character ISO 3166 standards country codeDictate 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.
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".

Basic subscription timing request and response

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'

Here is the request body JSON expanded:

{
  "customerCountryCode": "US",
  "customerPostalCode": "98103",
  "desiredDeliveryDate": "2021-11-20",
  "options": {
  	"shippingOptions": {
    	"fromCountryCode": "US",
    	"fromPostalCode": "98101",
    	"originId": "origin-id-123",
    	"shipOption": "Standard"
  }
},
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE",
    }
    ]
}

This is a typical response:

{
  "subscriptionTimingId": "8ffa82ab-e67a-4b9f-bed6-d3b29b088bb1",
  "customerCountryCode": "US",
  "customerPostalCode": "98103",
  "shippingOrigin": {
      "countryCode": "US",
      "postalCode": "97005",
      "shipiumOriginId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"
  },
  "desiredDeliveryDate": "2021-11-20T00:00:00Z",
  "shipByDate": "2021-11-17T22:00:00-07:00",
  "fcDropByDate": "2021-11-16T00:00:01-07:00",
  "estimateSource": "ShipiumCalculated",
  "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 FC from which the shipment will be sent; or
  • details of a shipOption other than Standard.

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'

Here is the request body JSON expanded:

{
  "customerCountryCode": "US", 
  "customerPostalCode": "98103", 
  "desiredDeliveryDate": "2020-04-20", 
  "options": {
    "shippingOptions": {
      "fromCountryCode": "US",
      "fromPostalCode": "87121",
      "shipOption": "Standard"
  }
},
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE",
    }
    ]
}

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

This is the response:

{
  "customerCountryCode": "US",
  "customerPostalCode": "98103",
  "desiredDeliveryDate": "2020-04-20T00:00:00Z",
  "fcDropByDate": "2020-04-17T00:00:00Z",
  "shippingOrigin": {
    "countryCode": "US",
    "postalCode": "87121",
    "shipiumOriginId": "3adcd9f9-06de-4620-894f-7b1e6db1a815"
  },
  "options": {
      "shippingOptions": {
      "fromCountryCode": "US", 
      "fromPostalCode": "87121", 
      "shipOption": "Standard"
      }
  },
  "shipByDate": "2020-04-18T00:00:00Z",
  "estimateSource": "ShipiumCalculated",
  "subscriptionTimingId": "b903b8b0-84b4-11ea-ab12-0800200c9a66",
  "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
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'

Here is the JSON request body expanded:

{
    "customerCountryCode": "US",
    "customerPostalCode": "98103",
    "desiredDeliveryDate": "2021-11-20",
    "options": {
      "shippingOptions": {
        "shipOption": "NextDay"
  }
},
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE",
    }
    ]
}

This example shows the response when extra options are used:

{
  "subscriptionTimingId": "169b7732-5e6d-4a91-90f8-9fc98439f1aa",
  "customerCountryCode": "US",
  "customerPostalCode": "98103",
  "shippingOrigin": {
      "countryCode": "US",
      "postalCode": "98327",
      "shipiumOriginId": "3adcd9f9-06de-4620-894f-7b1e6db1a815"
  },
  "options": {
      "shippingOptions": {
          "shipOption": "NextDay"
      }
  },
  "desiredDeliveryDate": "2021-11-20T00:00:00Z",
  "shipByDate": "2021-11-18T22:00:00-08:00",
  "fcDropByDate": "2021-11-17T00:00:01-08:00",
  "estimateSource": "ShipiumCalculated",
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
    ]
}

Ship from origin postal code override

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'

Here is the JSON request body expanded:

{
    "customerCountryCode": "US",
    "customerPostalCode": "98103",
    "desiredDeliveryDate": "2021-11-20T00:00:00.000000Z",
    "options": {
      "shippingOptions": {
        "fromCountryCode": "US",
        "fromPostalCode": "97005",
  }
},
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE",
    }
    ]
}

This example shows the response when extra options are used:

{
  "subscriptionTimingId": "93740852-b10f-45eb-bbcf-167260d956d7",
  "customerCountryCode": "US",
  "customerPostalCode": "98103",
  "shippingOrigin": {
      "countryCode": "US",
      "postalCode": "97005",
      "shipiumOriginId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"
  },
  "options": {
      "shippingOptions": {
          "fromCountryCode": "US",
          "fromPostalCode": "97005"
      }
  },
  "desiredDeliveryDate": "2021-11-20T00:00:00Z",
  "shipByDate": "2021-11-15T22:00:00-08:00",
  "fcDropByDate": "2021-11-12T00:00:01-08:00",
  "estimateSource": "ShipiumCalculated",
  "referenceIdentifiers": [
    {
      "name": "MY_KEY",
      "value": "MY_VALUE"
    }
    ]
}

Ship from origin override

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'

Here is the request body JSON expanded:

{
    "customerCountryCode": "US",
    "customerPostalCode": "98103",
    "desiredDeliveryDate": "2021-11-20T00:00:00.000000Z",
    "options": {
        "shippingOptions": {
            "originId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"
        }
    },
    "referenceIdentifiers": [
      {
        "name": "MY_KEY",
        "value": "MY_VALUE"
      }
      ]
}

This example shows the response 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": "97005",
      "shipiumOriginId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"
  },
  "desiredDeliveryDate": "2021-11-20T00:00:00Z",
  "shipByDate": "2021-11-16T22:00:00-08:00",
  "fcDropByDate": "2021-11-15T00:00:01-08:00",
  "estimateSource": "ShipiumCalculated",
  "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.