Subscription Timing API Details

Suggest Edits

Overview

Use the Subscription Timing API – /subscription/timing – to determine when a given subscription shipment should be shipped out and/or sent to a warehouse for shipping in order to hit a particular delivery date based on your company's historical shipping speeds and the location of the address to which the shipment is being sent.

When calling the 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.

We give some details below and walk through some typical examples.

📘

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 OAuth and API Key users.

🔐
Authenticating for Curl
Open Recipe

Subscription Timing API

This section gives both basic and advanced examples.

Basic Subscription Timing request and response

This example shows a typical Subscription Timing cURL request: 

curl --request POST \
  --url '<<api_url>>/api/v1/subscription/timing' \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data '{"customerCountryCode": "US","customerPostalCode": "84717","desiredDeliveryDate": "2021-11-20T00:00:00.000000Z"}'

And here is the body JSON expanded:

{
    "customerCountryCode": "US",
    "customerPostalCode": "84717",
    "desiredDeliveryDate": "2021-11-20T00:00:00.000000Z"
}

This is a typical response:

{
    "subscriptionTimingRequestId": "8ffa82ab-e67a-4b9f-bed6-d3b29b088bb1",
    "customerCountryCode": "US",
    "customerPostalCode": "84717",
    "shippingOrigin": {
        "countryCode": "US",
        "postalCode": "97005",
        "shipiumOriginId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"
    },
    "desiredDeliveryDate": "2021-11-20T00:00:00Z",
    "shipByDate": "2021-11-17T22:00:00-08:00",
    "fcDropByDate": "2021-11-16T00:00:01-08:00",
    "subscriptionTimingRequestExpiration": "2022-06-01T21:01:01.746Z"
}

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 cURL request:

curl --request POST \
  --url '<<api_url>>/api/v1/subscription/timing' \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data '{"customerCountryCode": "US", "customerPostalCode": "99163", "desiredDeliveryDate": "2020-04-20T00:00:00Z", "options": {"shippingOptions": {"fromCountryCode": "US", "fromPostalCode": "87121", "shipOption": "Standard"}}}'

This is the response:

{
  "customerCountryCode": "US",
  "customerPostalCode": "99163",
  "desiredDeliveryDate": "2020-04-20T00:00:00Z",
  "fcDropByDate": "2020-04-17T00:00:00Z",
  "options": {
      "shippingOptions": {
          "fromCountryCode": "US",
          "fromPostalCode": "87121",
          "shipOption": "Standard"
      }
  },
  "shipByDate": "2020-04-18T00:00:00Z",
  "subscriptionTimingRequestExpiration": "2020-04-16T00:00:00Z",
  "subscriptionTimingRequestId": "b903b8b0-84b4-11ea-ab12-0800200c9a66"
}

Call and response with advanced options

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

Ship Option Override

curl --request POST \
  --url '<<api_url>>/api/v1/subscription/timing' \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data '{"customerCountryCode": "US","customerPostalCode": "98036","desiredDeliveryDate": "2021-11-20T00:00:00.000000Z","options": {"shippingOptions": {"shipOption": "NextDay"}}}'

Here is the JSON body expanded:

{
    "customerCountryCode": "US",
    "customerPostalCode": "98036",
    "desiredDeliveryDate": "2021-11-20T00:00:00.000000Z",
    "options": {
        "shippingOptions": {
            "shipOption": "NextDay"
        }
    }
}

This example shows the response when extra options are used:

{
    "subscriptionTimingRequestId": "169b7732-5e6d-4a91-90f8-9fc98439f1aa",
    "customerCountryCode": "US",
    "customerPostalCode": "98036",
    "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",
    "subscriptionTimingRequestExpiration": "2022-06-01T21:02:13.253Z"
}

Ship From Country Postal Override

curl --request POST \
  --url '<<api_url>>/api/v1/subscription/timing' \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data '{"customerCountryCode": "US","customerPostalCode": "92801","desiredDeliveryDate": "2021-11-20T00:00:00.000000Z","options": {"shippingOptions": {"fromCountryCode": "US","fromPostalCode": "97005"}}}'

Here is the JSON body expanded:

{
    "customerCountryCode": "US",
    "customerPostalCode": "92801",
    "desiredDeliveryDate": "2021-11-20T00:00:00.000000Z",
    "options": {
        "shippingOptions": {
            "fromCountryCode": "US",
            "fromPostalCode": "97005"
        }
    }
}

This example shows the response when extra options are used:

{
    "subscriptionTimingRequestId": "93740852-b10f-45eb-bbcf-167260d956d7",
    "customerCountryCode": "US",
    "customerPostalCode": "92801",
    "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",
    "subscriptionTimingRequestExpiration": "2022-06-01T21:02:40.789Z"
}

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 '{"customerCountryCode": "US","customerPostalCode": "42701","desiredDeliveryDate": "2021-11-20T00:00:00.000000Z","options": {"shippingOptions": {"originId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"}}}'

{
    "customerCountryCode": "US",
    "customerPostalCode": "42701",
    "desiredDeliveryDate": "2021-11-20T00:00:00.000000Z",
    "options": {
        "shippingOptions": {
            "originId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"
        }
    }
}

{
    "subscriptionTimingRequestId": "a3be42a0-ab6b-47fa-a5f1-c720143e70f7",
    "customerCountryCode": "US",
    "customerPostalCode": "42701",
    "shippingOrigin": {
        "countryCode": "US",
        "postalCode": "97005",
        "shipiumOriginId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce"
    },
    "options": {
        "shippingOptions": {
            "originId": "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",
    "subscriptionTimingRequestExpiration": "2022-06-01T21:02:59.097Z"
}

📘

More information on the API responses

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

Updated 11 months ago