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`

Request and response fields for API calls

The following tables provide required, conditional, and optional field descriptions for calling the Shipment Planning API. You can find additional support in the Shipment Planning API Reference.

Required request fields

Field	Details
`shipmentParameters.destinationAddress .countryCode`	Type: String Description: The ISO 3166-1 country code for the destination address
`shipmentParameters.destinationAddress .postalCode`	Type: String Description: A country-code-appropriate postal code for the destination address

Conditional request fields

Field	Details
`shipmentParameters.originId`	Type: String Condition: Required if `countryCode` and `postalCode` are not provided for the ship-from address Description: A unique identifier associated with the shipping origin
`shipmentParameters.shipFromAddress .countryCode`	Type: String Condition: Required if `originId` is not provided Description: The ISO 3166-1 country code for the origin address
`shipmentParameters.shipFromAddress .postalCode`	Type: String Condition: Required if `originId` is not provided Description: A country-code-appropriate postal code for the origin address
`businessDaysOfTransit`	Type: Integer (int32) Example: `2` Condition: Cannot be included with `desiredDeliveryDate`. Requires either `mustShipByDate`, `mustShipByBusinessDays`, or `mustShipByCalendarDays`. Description: An integer number of business days by which the shipment must be delivered
`mustShipByDate`	Type: String Example: `2020-04-20` Condition: Cannot be included with `mustShipByBusinessDays` or `mustShipByCalendarDays`. Required when including `businessDaysOfTransit` if `mustShipByBusinessDays` and `mustShipByCalendarDays` are not provided. Description: A date value specifying when the shipment needs to be shipped by (in the timezone of the fulfillment center from which it is shipping)
`mustShipByBusinessDays`	Type: Integer (int32) Example: `2` Condition: Cannot be included with `mustShipByDate` or `mustShipByCalendarDays`. Required when including `businessDaysOfTransit` if `mustShipByDate` and `mustShipByCalendarDays` are not provided. Description: An integer number of business days by which the shipment must be shipped from the fulfillment center
`mustShipByCalendarDays`	Type: Integer (int32) Example: `3` Condition: Cannot be included with `mustShipByDate` or `mustShipByBusinessDays`. Required when including `businessDaysOfTransit` if `mustShipByDate` and `mustShipByBusinessDays` are not provided. Description: An integer number of calendar days by which the shipment must be shipped from the fulfillment center
`deliveryWindowDaysType`	Type: String (enumeration) Values: `calendar`, `business` Condition: Cannot be provided without `deliveryWindowDays` Description: Specifies how days are counted when evaluating the delivery window. `Calendar` counts all days; `business` counts only Monday–Friday, skipping weekends. Defaults to `calendar`.

Optional request fields

Field	Details
`requestDateOverride`	Type: String Example: `2019-10-31T20:00:00Z` Description: Overrides the request date to a specific date and time from which the ship-by and drop-by date are calculated
`desiredDeliveryDate`	Type: String Example: `2019-10-31T20:00:00Z` Description: 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. Cannot be included when including a value for `businessDaysOfTransit`.
`desiredDeliveryDateOptions .exactDateDelivery`	Type: Boolean Values: `true`, `false` Description: Indicates that shipment carrier selection and exact date delivery are targeting the requested desired delivery date with no tolerance for before or after. Defaults to `false`.
`deliveryWindowDays`	Type: Integer (int32) Example: `3` Description: The maximum number of acceptable days before the `desiredDeliveryDate` for delivery. When set to `0`, this behaves like `exactDateDelivery: true`. Requires a `desiredDeliveryDate` to be provided and must be >= 0 if included. You can find more information in Desired, Exact, & Guaranteed Delivery Dates.
`carrierServiceMethodAllowList`	Type: String Example: `ups-ground-service-method` Description: A list of `carrierServiceMethodId` and/or carriers that should be considered for selection. Either `carrierServiceMethodAllowList` or `shipOption` may be provided but not both. See Supported Carriers for carrier service method IDs.
`shipmentParameters.shipFromAddress .street1`	Type: String Description: The first origin address line
`shipmentParameters.shipFromAddress .street2`	Type: String Description: The second origin address line
`shipmentParameters.shipFromAddress .city`	Type: String Description: The name of the city for the origin address
`shipmentParameters.shipFromAddress .state`	Type: String Description: The 2-letter postal abbreviation of the state for the origin address
`shipmentParameters.shipFromAddress .addressType`	Type: String (enumeration) Values: `commercial`, `residential` Description: The type of location for the origin address. Defaults to `residential`.
`shipmentParameters.destinationAddress .street1`	Type: String Description: The first destination address line
`shipmentParameters.destinationAddress .street2`	Type: String Description: The second destination address line
`shipmentParameters.destinationAddress .city`	Type: String Description: The name of the city for the destination address
`shipmentParameters.destinationAddress .state`	Type: String Description: The 2-letter postal abbreviation of the state for the destination address
`shipmentParameters.destinationAddress .addressType`	Type: String (enumeration) Values: `commercial`, `residential` Description: The type of location for the destination address. Defaults to `residential`.
`shipmentParameters.fulfillmentContext`	Type: String Description: Fulfillment context alias used in the fulfillment context detail search
`shipmentParameters.fulfillmentType`	Type: String (enumeration) Values: `at_large`, `customer`, `hundredweight`, `reship`, `returns`, `unknown` Description: The fulfillment methodology of the shipment
`shipmentParameters.shipOption`	Type: String Example: `standard` Description: A high-level shipping option shown to or selected by a customer. Either `carrierServiceMethodAllowList` or `shipOption` may be provided but not both.
`shipmentParameters .deliverySignatureOption`	Type: String (enumeration) Values: `AdultResidentSignature`, `AdultSignature`, `None`, `ResidentSignature`, `Signature`, `Unknown` Description: A delivery signature option passed in the API request. Defaults to `none`.
`shipmentParameters.testMode`	Type: Boolean Values: `true`, `false` Description: When `true`, indicates that a test shipment will be created with carriers and service methods considered in test mode.
`partnerReferenceIdentifier`	Type: String Description: A reference identifier your organization can provide to use for reporting purposes
`referenceIdentifier`	Type: String Description: An optional identifier you can provide to reference the shipment
`referenceIdentifiers.name`	Type: String Description: Your organization's own identifier to be associated with the shipment for internal tracking
`referenceIdentifiers.value`	Type: String Description: Your organization's own value to be associated with the specified name for internal tracking

Response attributes

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.

Control delivery timing

The Shipment Planning API provides several options for controlling when a shipment can be delivered. Understanding these options helps you balance delivery precision against carrier flexibility and cost.

Default behavior (any early delivery)

When you provide a desiredDeliveryDate without additional constraints, the API accepts any carrier service method that can deliver on or before that date. This provides the most carrier options and typically the lowest cost, but deliveries may arrive earlier than expected.

Delivery windows

Use deliveryWindowDays to specify the maximum number of days before the desiredDeliveryDate that are acceptable. For example, setting deliveryWindowDays to 3 means delivery can occur on the desired date or up to 3 days early. Set deliveryWindowDaysType to BUSINESS to count only weekdays, or leave it as the default CALENDAR to count all days. This option is useful for businesses that need to control delivery timing without requiring exact-date precision.

Exact date delivery

Set desiredDeliveryDateOptions.exactDateDelivery to true to restrict carrier selection to only service methods with a high probability of delivering on the exact date specified. This provides the most precise delivery timing but significantly limits carrier options and may result in higher shipping costs.

Business days of transit

Use businessDaysOfTransit as an alternative to desiredDeliveryDate when you want to specify delivery timing relative to the ship date rather than as an absolute date. This option requires either mustShipByDate, mustShipByBusinessDays, or mustShipByCalendarDays to be included. This approach is common for 3PLs and fulfillment partners with contractual service level agreements.

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 delivery window

This example shows a request for a customer who can accept delivery up to 3 business days before their desired delivery date of December 19, 2024.

{
  "requestDateOverride": "2024-12-10T10:00:00Z",
  "desiredDeliveryDate": "2024-12-19T00:00:00Z",
  "deliveryWindowDays": 3,
  "deliveryWindowDaysType": "BUSINESS",
  "carrierServiceMethodAllowList": [],
  "shipmentParameters": {
    "shipFromAddress": {
      "street1": "123 Main St.",
      "city": "Seattle",
      "state": "WA",
      "countryCode": "US",
      "postalCode": "98101",
      "addressType": "commercial"
    },
    "destinationAddress": {
      "street1": "456 Oak Ave.",
      "city": "Los Angeles",
      "state": "CA",
      "countryCode": "US",
      "postalCode": "90001",
      "addressType": "commercial"
    },
    "fulfillmentType": "customer",
    "shipOption": "standard"
  },
  "partnerReferenceIdentifier": "shipmentPlanWindow1"
}

When using BUSINESS days, the API counts backward from the desired delivery date, skipping weekends. For this example with a desired delivery date of December 19, 2024 (Thursday) and a 3-business-day window, the acceptable delivery dates are December 16–19, 2024.

Date	Day	Business days early	Acceptable?
Dec. 19	Thursday	0	Yes
Dec. 18	Wednesday	1	Yes
Dec. 17	Tuesday	2	Yes
Dec. 16	Monday	3	Yes
Dec. 15	Sunday	(skipped)	—
Dec. 14	Saturday	(skipped)	—
Dec. 13	Friday	4	No

Example response body using delivery window

{
  "shipmentPlanningId": "9a2b3c4d-e5f6-7890-abcd-ef1234567890",
  "shippingOrigin": {
    "countryCode": "US",
    "postalCode": "98101",
    "shipiumOriginId": "d1135cd9-3f8b-4a54-b8cb-573f0ab6870d",
    "originProcessingDays": 1.0
  },
  "carrierServiceMethodAllowList": [],
  "shipmentParameters": {
    "shipFromAddress": {
      "street1": "123 Main St.",
      "city": "Seattle",
      "state": "WA",
      "countryCode": "US",
      "postalCode": "98101",
      "addressType": "commercial"
    },
    "destinationAddress": {
      "street1": "456 Oak Ave.",
      "city": "Los Angeles",
      "state": "CA",
      "countryCode": "US",
      "postalCode": "90001",
      "addressType": "commercial"
    },
    "fulfillmentType": "customer",
    "shipOption": "standard"
  },
  "desiredDeliveryDate": "2024-12-19T00:00:00Z",
  "deliveryWindowDays": 3,
  "deliveryWindowDaysType": "BUSINESS",
  "requestDateOverride": "2024-12-10T10:00:00Z",
  "shipByDate": "2024-12-13T22:00:00-08:00",
  "fcDropByDate": "2024-12-12T00:00:01-08:00",
  "estimateSource": "ShipiumCalculated",
  "estimatedTransitDays": 3,
  "shipDateException": false,
  "partnerReferenceIdentifier": "shipmentPlanWindow1"
}

If no carrier service method can deliver within the specified window, the API returns a 400 Bad Request error. When this occurs, consider expanding the delivery window, adjusting the desired delivery date, or modifying other constraints.

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: