Get started

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

Retrieve shipment planning guidance from the Shipment Planning API

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

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

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

Request field	Required/Optional	Field properties	Description
`requestDate Override`	Optional	String Ex.: `2019-10-31T20:00:00Z`	Overrides the request date to a specific date and time from which the ship-by and drop-by date are calculated
`desiredDelivery Date`	Optional	String Ex.: `2019-10-31T20:00:00Z`	The string representation of either an ISO-8601 date or a local date for desired delivery: yyyy-mm-dd. The date or date-time the package is intended to arrive to the customer. This is used to determine the most appropriate service method when generating a label. The `businessDaysOfTransit` may be used instead of `desiredDeliveryDate`, but a value for `desiredDeliveryDate` cannot be included when including a value for `businessDaysOfTransit`.
`businessDaysOf Transit`	Optional	Integer Ex.: `2`	An integer number of business days by which the shipment must be delivered; this value is used as an alternative to `desiredDeliveryDate` and cannot be included when including a value for `desiredDeliveryDate`. When including `businessDaysOfTransit`, you must also include either `mustShipByDate` or `mustShipByBusinessDays`.
`mustShipByDate`	Optional	String Ex.: `2020-04-20`	A date value specifying when the shipment needs to be shipped by (in the timezone of the fulfillment center from which it is shipping); the `mustShipByBusinessDays` or `mustShipByCalendarDays` may be used instead of `mustShipByDate`, but a value for `mustShipByDate` cannot be included when including a value for `mustShipByBusinessDays` or `mustShipByCalendarDays`. Either mustShipByBusinessDays``mustShipByCalendarDays, or `mustShipByDate` must be included when including `businessDaysOfTransit`.
`mustShipByBusiness Days`	Optional	Integer Ex.: `2`	An integer number of business days by which the shipment must be shipped from the fulfillment center. This value is used as an alternative to `mustShipByDate` and cannot be included when including a value for `mustShipByDate`. Either mustShipByBusinessDays``mustShipByCalendarDays, or `mustShipByDate` must be included when including `businessDaysOfTransit`.
`mustShipByCalendar Days`	Optional	Integer Ex.: `3`	An integer number of calendar days by which the shipment must be shipped from the fulfillment center. This value is used as an alternative to `mustShipByDate` and cannot be included when including a value for `mustShipByDate`. Either mustShipByBusinessDays``mustShipByCalendarDays, or `mustShipByDate` must be included when including `businessDaysOfTransit`.
`desiredDelivery DateOptions .exactDateDelivery`	Optional	Boolean `true` or `false`	This optional flag indicates that a shipment carrier selection and exact date delivery is targeting the requested desired delivery date with no tolerance for before or after. The default value is `false`.
`carrierService MethodAllowList`	Optional	String Ex.: `ups-ground-service-method`	A list of `carrierServiceMethodId` and/or carriers that should be considered for selection; either `carrierServiceMethodAllowList` or `shipOption` may be provided but not both.
`shipmentParameters .originId`	Optional, but required if `countryCode` and `postalCode` are not provided for the ship-from address	String	A unique identifier associated with the shipping origin; when this value is absent, the `countryCode` and `postalCode` for the ship-from address are required.
`shipmentParameters .shipFromAddress .street1`	Optional	String	The first origin address line
`shipmentParameters .shipFromAddress .street2`	Optional	String	The second origin address line
`shipmentParameters .shipFromAddress .city`	Optional	String	The name of the city for the origin address
`shipmentParameters .shipFromAddress .state`	Optional	String	The two-letter postal abbreviation of the state for the origin address
`shipmentParameters .shipFromAddress .countryCode`	Optional, but required if `originId` is not provided	String	The ISO 3166-1 country code for the origin address; when this value is absent, the `originId` is required.
`shipmentParameters .shipFromAddress .postalCode`	Optional, but required if `originId` is not provided	String	A country-code-appropriate postal code for the origin address; when this value is absent, the `originId` is required.
`shipmentParameters .shipFromAddress .addressType`	Optional	String enumeration Values are: `commercial` `residential`	The type of location for the origin address; the default value is `residential`.
`shipmentParameters .destinationAddress .street1`	Optional	String	The first destination address line
`shipmentParameters .destinationAddress .street2`	Optional	String	The second destination address line
`shipmentParameters .destinationAddress .city`	Optional	String	The name of the city for the destination address
`shipmentParameters .destinationAddress .state`	Optional	String	The 2-letter postal abbreviation of the state for the destination address
`shipmentParameters .destinationAddress .countryCode`	Required	String	The ISO 3166-1 country code for the destination address
`shipmentParameters .destinationAddress .postalCode`	Required	String	A country-code-appropriate postal code for the destination address
`shipmentParameters .destinationAddress .addressType`	Optional	String enumeration Values are: `commercial` `residential`	The type of location for the destination address; the default value is `residential`.
`shipmentParameters .fulfillment Context`	Optional	String	Fulfillment context alias used in the fulfillment context detail search
`shipmentParameters .fulfillmentType`	Optional	String enumeration Values are: `at_large` `customer` `hundredweight` `reship` `returns` `unknown`	The fulfillment methodology of the shipment
`shipmentParameters .shipOption`	Optional	String Ex.: `standard`	A high-level shipping option shown to or selected by a customer; either `carrierServiceMethodAllowList` or `shipOption` may be provided but not both.
`shipmentParameters .deliverySignature Option`	Optional	String enumeration Values are: -`AdultResidentSignature` `AdultSignature` `None` `ResidentSignature` `Signature` `Unknown`	A delivery signature option passed in the API request; the default value is none.
`shipmentParameters .testMode`	Optional	Boolean `true` or `false`	When `true`, this indicates that a test shipment will be created with carriers and service methods considered in test mode.
`partnerReference Identifier`	Optional	String No character limitations	A reference identifier your organization can provide to use for reporting purposes
`referenceIdentifier`	Optional	String No character limitations	An optional identifier you can provide to reference the shipment
`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 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 attribute	Description
`shipmentPlanningId`	Unique Shipium-generated ID associated with the request and response
`fcDropByDate`	The 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.
`shipByDate`	The date by which the FC should ship the shipment in order to hit the desired delivery date that was requested.
`estimateSource`	The source of the times in transit (TNTs) that were utilized as part of the calculation. This will be one of `ShipiumCalculated`, `PartnerProvided`, or `CarrierProvided`.
`estimatedTransitDays`	The number of transit days between the desired delivery date and the estimated ship by date
`shipDateException`	A boolean value that is `true` only if some exception in providing a `shipByDate` exists

In addition to these primary response elements, if the requested desired delivery date would have required a ship date in the past, the shipDateExceptionDetails attributes in the following table will be returned in the response as well as shipDateException being set to true.

Response attribute	Description
`shipDateExceptionDetails.exceptions .exceptionType`	The type of exception for the ship date calculation exception (`Exact Delivery Date Not Supported`, `Ship Date In Past`, `Early Delivery Date`, `Late Delivery Date`, `FC Drop By Date In Past`, `Ship Date Past Must Ship By`)
`shipDateExceptionDetails.exceptions .exceptionDescription`	A description of the type of exception for the ship date calculation exception
`shipDateExceptionDetails .effectiveShipByDate`	Provides an effective ship-by date in the local timezone of the origin
`shipDateExceptionDetails .effectiveFcDropByDate`	Provides an effective FC drop-by date in the local timezone of the origin
`shipDateExceptionDetails .effectiveDeliveryDate`	Provides an effective delivery date in the local timezone of the destination

When the Shipment Planning 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 shipping cutoff time for the selected carrier and service method configured 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 carrier service method configured for the FC was 14:00, the resulting exception ship date would be 2024-06-14T14:00:00-06:00.

Basic shipment planning request and response

Example cURL call

This example shows a typical Shipment Planning API call cURL request:

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

Example request body using ship option

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

{
  "requestDateOverride": "2024-08-20T10:50:42Z",
  "desiredDeliveryDate": "2024-08-24T23:59:59-04:00",
  "desiredDeliveryDateOptions": {
      "exactDateDelivery": false
    },
  "carrierServiceMethodAllowList": [],
  "shipmentParameters": {
    "shipFromAddress": {
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "commercial"
    },
    "destinationAddress": {
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "commercial"
    },
    "fulfillmentContext": "123456",
    "fulfillmentType": "customer",
    "shipOption": "standard",
    "deliverySignatureOption": "none"
  },
  "partnerReferenceIdentifier": "shipmentPlanA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
        {
          "name": "order-instance-ID",
          "value": "1350000_2024-08-20 00:01:26 UTC"
        }
  ],
}

Example response body using ship option

{
  "shipmentPlanningId": "8ffa82ab-e67a-4b9f-bed6-d3b29b088bb1",
  "shippingOrigin": {
      "countryCode": "US",
      "postalCode": "98101",
      "shipiumOriginId": "d1135cd9-3f8b-4a54-b8cb-573f0ab6870d",
      "originProcessingDays": 1.0
  },
  "carrierServiceMethodAllowList": [],
  "shipmentParameters": {
    "shipFromAddress": {
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Seattle",
      "state": "WA",
      "countryCode": "US",
      "postalCode": "98101",
      "addressType": "commercial"
    },
    "destinationAddress": {
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "commercial"
    },
    "fulfillmentContext": "123456", 
    "fulfillmentType": "customer",
    "shipOption": "standard",
    "deliverySignatureOption": "none"
  },
  "desiredDeliveryDate": "2021-11-20T00:00:00Z",
  "desiredDeliveryDateOptions": {
      "exactDateDelivery": false
    },
  "requestDateOverride": "2024-08-20T10:50:42Z",
  "shipByDate": "2021-11-17T22:00:00-07:00",
  "fcDropByDate": "2021-11-16T00:00:01-07:00",
  "estimateSource": "ShipiumCalculated",
  "estimatedTransitDays": 3,
  "shipDateException": false,
  "partnerReferenceIdentifier": "shipmentPlanA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
        {
          "name": "order-instance-ID",
          "value": "1350000_2024-08-20 00:01:26 UTC"
        }
    ]
}

Example response body using ship option with a ship date exception

In the event that there is an issue with providing back a shipByDate for the passed desiredDeliveryDate, the API will set the field shipDateException to true and provide details for the best possible effectiveShipByDate and effectiveDeliveryDate based on the passed parameters.

{
  "shipmentPlanningId": "8ffa82ab-e67a-4b9f-bed6-d3b29b088bb1",
  "shippingOrigin": {
      "countryCode": "US",
      "postalCode": "97005",
      "shipiumOriginId": "a97a9ffc-ce6c-44dd-9831-7497bf0838ce",
      "originProcessingDays": 1.0
  },
  "carrierServiceMethodAllowList": [],
  "shipmentParameters": {
    "shipFromAddress": {
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Seattle",
      "state": "WA",
      "countryCode": "US",
      "postalCode": "98101",
      "addressType": "commercial"
    },
    "destinationAddress": {
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "commercial"
    },
    "fulfillmentContext": "123456",  
    "fulfillmentType": "customer",
    "shipOption": "standard",
    "deliverySignatureOption": "none"
  },
  "desiredDeliveryDate": "2021-11-20T00:00:00Z",
  "desiredDeliveryDateOptions": {
      "exactDateDelivery": false
    },
  "requestDateOverride": "2024-08-20T10:50:42Z",
  "shipByDate": "2021-11-15T11:09:52.071939792-07:00",
  "fcDropByDate": "2021-11-16T00:00:01-07:00",
  "estimateSource": "ShipiumCalculated",
  "estimatedTransitDays": 3,
  "shipDateException": true,
  "shipDateExceptionDetails": {
    "exceptions": [
      {
        "exceptionType": "LateDeliveryDate",
        "exceptionDescription": "The effectiveShipByDate results in a delivery date past the desiredDeliveryDate."
      }
    ],
    "effectiveFcDropByDate": "2021-11-17T21:00:00-07:00",
    "effectiveShipByDate": "2021-11-17T22:00:00-07:00",
    "effectiveDeliveryDate": "2021-11-21T22:00:00-07:00"
  },
  "partnerReferenceIdentifier": "shipmentPlanA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
        {
          "name": "order-instance-ID",
          "value": "1350000_2024-09-30 00:01:26 UTC"
        }
    ]
}

Example request body using carrier service method allow list

{
  "requestDateOverride": "2024-08-20T10:50:42Z",
  "desiredDeliveryDate": "2024-08-24T23:59:59-04:00",
  "desiredDeliveryDateOptions": {
      "exactDateDelivery": false
    },
  "carrierServiceMethodAllowList": [
    "usps-ground-advantage-service-method",
    "ups-ground-service-method"
  ],
  "shipmentParameters": {
    "shipFromAddress": {
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "commercial"
    },
    "destinationAddress": {
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "commercial"
    },
    "fulfillmentContext": "123456",  
    "fulfillmentType": "customer",
    "shipOption": null,
    "deliverySignatureOption": "none"
  },
  "partnerReferenceIdentifier": "shipmentPlanA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
        {
          "name": "order-instance-ID",
          "value": "1350000_2024-08-20 00:01:26 UTC"
        }
  ],
}

Example response body using carrier service method allow list

{
  "shipmentPlanningId": "8ffa82ab-e67a-4b9f-bed6-d3b29b088bb1",
  "shippingOrigin": {
      "countryCode": "US",
      "postalCode": "98101",
      "shipiumOriginId": "d1135cd9-3f8b-4a54-b8cb-573f0ab6870d",
      "originProcessingDays": 1.0
  },
  "carrierServiceMethodAllowList": [
    "usps-ground-advantage-service-method",
    "ups-ground-service-method"
  ],
  "shipmentParameters": {
    "shipFromAddress": {
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Seattle",
      "state": "WA",
      "countryCode": "US",
      "postalCode": "98101",
      "addressType": "commercial"
    },
    "destinationAddress": {
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "commercial"
    },
    "fulfillmentContext": "123456",  
    "fulfillmentType": "customer",
    "shipOption": null,
    "deliverySignatureOption": "none"
  },
  "desiredDeliveryDate": "2021-11-20T00:00:00Z",
  "desiredDeliveryDateOptions": {
      "exactDateDelivery": false
    },
  "requestDateOverride": "2024-08-20T10:50:42Z",
  "shipByDate": "2021-11-17T22:00:00-07:00",
  "fcDropByDate": "2021-11-16T00:00:01-07:00",
  "estimateSource": "ShipiumCalculated",
  "estimatedTransitDays": 3,
  "shipDateException": false,
  "partnerReferenceIdentifier": "shipmentPlanA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
        {
          "name": "order-instance-ID",
          "value": "1350000_2024-08-20 00:01:26 UTC"
        }
    ]
}

Example request body using ship option and business days of transit

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

{
  "requestDateOverride": "2021-11-20T10:50:42Z",
  "businessDaysOfTransit": "2",
  "mustShipByDate": "2021-11-29",
  "carrierServiceMethodAllowList": [],
  "shipmentParameters": {
    "shipFromAddress": {
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "commercial"
    },
    "destinationAddress": {
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "commercial"
    },
    "fulfillmentContext": "123456",
    "fulfillmentType": "customer",
    "shipOption": "standard",
    "deliverySignatureOption": "none",
    "testMode": false,
  },
  "partnerReferenceIdentifier": "shipmentPlanA1",
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
        {
          "name": "order-instance-ID",
          "value": "1350000_2021-11-20 00:01:26 UTC"
        }
  ],
}

Example response body using ship option and business days of transit

{
  "shipmentPlanningId": "8ffa82ab-e67a-4b9f-bed6-d3b29b088bb1",
  "shippingOrigin": {
      "countryCode": "US",
      "postalCode": "98101",
      "shipiumOriginId": "d1135cd9-3f8b-4a54-b8cb-573f0ab6870d",
      "originProcessingDays": 1.0
  },
  "carrierServiceMethodAllowList": [],
  "shipmentParameters": {
    "shipFromAddress": {
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Seattle",
      "state": "WA",
      "countryCode": "US",
      "postalCode": "98101",
      "addressType": "commercial"
    },
    "destinationAddress": {
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "commercial"
    },
    "fulfillmentContext": "123456", 
    "fulfillmentType": "customer",
    "shipOption": "standard",
    "deliverySignatureOption": "none"
  },
  "businessDaysOfTransit": "2",
  "mustShipByDate": "2021-11-29",
  "requestDateOverride": "2021-11-20T10:50:42Z",
  "shipByDate": "2021-11-27T22:00:00-07:00",
  "fcDropByDate": "2021-11-26T00:00:01-07:00",
  "estimateSource": "ShipiumCalculated",
  "estimatedTransitDays": 2,
  "shipDateException": false,
  "partnerReferenceIdentifier": "shipmentPlanA1",
  "testMode": false,
  "referenceIdentifier": "76d8e547-a553-4627-b721-ccfcf350c866",
  "referenceIdentifiers": [
        {
          "name": "order-instance-ID",
          "value": "1350000_2021-11-20 00:01:26 UTC"
        }
    ]
}

Shipment planning request and response with minimal requirements

Example cURL request

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

Example request body

{
  "desiredDeliveryDate": "2024-08-24T23:59:59-04:00",
  "shipmentParameters": {
    "destinationAddress": {
      "countryCode": "US",
      "postalCode": "10005", 
      "addressType": "commercial"
    },
  },
  "partnerReferenceIdentifier": "shipmentPlanD1"
}

Example response body

{
  "shipmentPlanningId": "8ffa82ab-e67a-4b9f-bed6-d3b29b088bb1",
  "shippingOrigin": {
      "countryCode": "US",
      "postalCode": "98101",
      "shipiumOriginId": "d1135cd9-3f8b-4a54-b8cb-573f0ab6870d",
      "originProcessingDays": 1.0
  },
  "carrierServiceMethodAllowList": [],
  "shipmentParameters": {
    "shipFromAddress": null,
    "destinationAddress": {
      "street1": null,
      "street2": null,
      "city": null,
      "state": null,
      "countryCode": "US",
      "postalCode": "10005",
      "addressType": "commercial"
    },
    "fulfillmentContext": null,  
    "shipOption": "standard",
    "deliverySignatureOption": "none"
  },
  "desiredDeliveryDate": "2024-08-24T23:59:59-04:00",
  "desiredDeliveryDateOptions": {
      "exactDateDelivery": false
    },
  "shipByDate": "2021-11-17T22:00:00-07:00",
  "fcDropByDate": "2021-11-16T00:00:01-07:00",
  "estimateSource": "ShipiumCalculated",
  "estimatedTransitDays": 3,
  "shipDateException": false,
  "partnerReferenceIdentifier": "shipmentPlanD1"
}

📘
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: