---
title: "Shipment Planning API"
method: POST
path: "/api/v1/deliveryexperience/shipmentPlanning"
tags: ["shipmentPlanning"]
---

# Shipment Planning API

`POST /api/v1/deliveryexperience/shipmentPlanning`

Determine when a shipment should drop to the fc and ship by to arrive by a date.

## Headers

- `X-DELEGATED-PARTNER-ID` string

## Request body

- ShipmentPlanningParameters — Information used to generate a shipment planning decision.
  - `requestDateOverride` string, date-time — Overrides the requestDate to a specific date & time from which the ship by and drop by date are calculated. ISO 8601 format
  - `desiredDeliveryDate` string — The string representation of either an ISO-8601 date or a LocalDate: yyyy-mm-dd. The date on which you want the shipment in question to be delivered on or before.
  - `businessDaysOfTransit` integer — An integer number of business days by which the shipment must be delivered. Used as an alternative to desiredDeliveryDate and cannot be passed with desiredDeliveryDate.
  - `mustShipByDate` string, date — A date value specifying when the shipment needs to be shipped by (in the timezone of the FC from which it is shipping). Mutually exclusive with mustShipByBusinessDays and mustShipByCalendarDays.
  - `mustShipByBusinessDays` integer — An integer number of business days by which the shipment must be shipped from the FC. Mutually exclusive with mustShipByDate and mustShipByCalendarDays.
  - `mustShipByCalendarDays` integer — An integer number of calendar days by which the shipment must be shipped from the FC. Mutually exclusive with mustShipByDate and mustShipByBusinessDays.
  - `deliveryWindowDays` integer — An integer number of days before the desiredDeliveryDate that defines the earliest acceptable delivery date. Used to determine if candidates are too early for the delivery window. Optional - if not provided, there is no earliest delivery constraint.
  - `deliveryWindowDaysType` 'BUSINESS' | 'CALENDAR' — The type of days to use when calculating the delivery window: BUSINESS for business days, CALENDAR for calendar days. Can only be set if deliveryWindowDays is provided. If deliveryWindowDays is provided without this field, CALENDAR is assumed.
  - `desiredDeliveryDateOptions` DesiredDeliveryDateOptions — Options for how the system will use the desiredDeliveryDate
    - `exactDateDelivery` boolean — This will restrict carrier selection to only use service methods that we have a high chance of making it there on time.
  - `carrierServiceMethodAllowList` string[] — A list of carrierServiceMethodId and/or carriers that should be considered for selection.
  - `shipmentParameters` SPShipmentParameters, required — Details of the shipment and its corresponding package and to/from addresses.
    - `shipFromAddress` SPAddress — The address of the location where the package is being delivered.
      - `street1` string — The first address line.
      - `street2` string — The second address line.
      - `city` string — The name of the city for the address.
      - `state` string — The name of the state for the address.
      - `countryCode` string, required — The ISO 3166-1 country code for the address.
      - `postalCode` string, required — A countryCode-appropriate postal code for the address.
      - `addressType` 'commercial' | 'residential' — The type of location for this address. Defaults to residential
    - `destinationAddress` SPAddress, required — The address of the location where the package is being delivered.
      - `street1` string — The first address line.
      - `street2` string — The second address line.
      - `city` string — The name of the city for the address.
      - `state` string — The name of the state for the address.
      - `countryCode` string, required — The ISO 3166-1 country code for the address.
      - `postalCode` string, required — A countryCode-appropriate postal code for the address.
      - `addressType` 'commercial' | 'residential' — The type of location for this address. Defaults to residential
    - `originId` string — The provided identifier of the origin or the shipium originId. This is exclusive with shipFromAddress and fulfillmentContextId.
    - `deliverySignatureOption` string — Defaults to None
    - `fulfillmentContext` string — A fulfillmentContext alias to use in the FulfillmentContextDetail search.
    - `fulfillmentType` string — Fulfillment methodology of the shipment.
    - `shipOption` string — A high-level shipping option shown to or selected by a customer.
    - `testMode` boolean — Indicates that a test shipment will be created with carriers and service methods considered in test mode.
    - `labelToDockDoorHours` number, double — An override for the origin config of the estimated time in hours between a label being printed and the shipment reaching the dock door.
  - `referenceIdentifier` string — Reference external identifier that is used for reporting purposes.
  - `partnerReferenceIdentifier` string — Reference external identifier explicitly provided by the partner. Used for reporting purposes.
  - `partnerReferenceIdentifier2` string — Secondary reference external identifier explicitly provided by the partner. Used for reporting purposes.
  - `referenceIdentifiers` ReferenceIdentifier[] — Reference external identifiers that are used for reporting purposes.
    - `name` string
    - `value` string
  - `shipmentTags` string[] — Free-form list of shipment tags for this planning request. Used for downstream reporting. Matches the shipmentTags field on the corresponding Carrier Selection API request.
  - `options` Options
    - `shippingOptions` ShippingOptions — Optional shipping information used as part of the Delivery Experience APIs.
      - `shipOption` 'NotProvided' | 'Standard' | 'StandardPlus' | 'SameDay' | 'NextDay' | 'Overnight' | 'PriorityOvernight' | 'TwoDay' | 'TwoDayMorning' | 'ThreeDay' | 'International24Hour' | 'InternationalOneToThreeDayEarly' | 'InternationalOneToThreeDay' | 'InternationalTwoToFiveDay' | 'InternationalTwoToTenDay' | 'InternationalOneToTwoWeek' | 'InternationalOneToFourWeek' | 'DesiredDeliveryDate' | 'BusinessDaysOfTransit' | 'Unknown' — A high-level shipping option shown to or selected by a customer.
      - `fromCountryCode` string — The ISO 3166-1 country code (alpha-2) from where the package is shipping from. Exclusive with originId.
      - `fromPostalCode` string — A country-appropriate postal code for the country defined in fromCountry. Exclusive with originId.
      - `originId` string — The provided identifier of the origin or the shipium originId. This is exclusive with fromCountryCode and fromPostalCode.
      - `estimateSource` 'PartnerProvided' | 'ShipiumCalculated' | 'CarrierProvided' | 'Unknown' — The source (ShipiumGenerated, PartnerProvided, or CarrierDefault) used to generate the estimate.
      - `deliveryBehaviorOverrides` DeliveryBehaviorOverrides — Optional overrides for weekend and holiday delivery behavior. When provided, these override partner-level configuration for the request.
        - `saturdayDeliveryBehavior` 'ALLOW' | 'NON_DELIVERY_DAY' | 'NON_TRANSIT_NON_DELIVERY_DAY' — Override for Saturday delivery behavior. When provided, overrides partner-level configuration for Saturday deliveries.
        - `sundayDeliveryBehavior` 'ALLOW' | 'NON_DELIVERY_DAY' | 'NON_TRANSIT_NON_DELIVERY_DAY' — Override for Sunday delivery behavior. When provided, overrides partner-level configuration for Sunday deliveries.
        - `holidayDeliveryBehavior` 'ALLOW' | 'NON_DELIVERY_DAY' | 'NON_TRANSIT_NON_DELIVERY_DAY' — Override for holiday delivery behavior. When provided, overrides partner-level configuration for holiday deliveries.
      - `timeInTransitSetting` string — Optional per-request override for time-in-transit aggressiveness. Overrides the account-level default for this request. One of: aggressive, standard, conservative, very_conservative. Values are case-sensitive.
  - `customerCountryCode` string
  - `customerPostalCode` string

## Response `200`

Shipment Planning successfully calculated.

- ShipmentPlanning
  - `shipmentPlanningId` string, required — An automatically generated id associated with this request. Multiple calls with the same inputs may return the same response and same shipmentPlanningId, though it is not guaranteed.
  - `shippingOrigin` ShippingOrigin, required — The predicted origin that the package is shipping from.
    - `countryCode` string — The ISO 3166-1 country code (alpha-2) representing where the package is shipping from.
    - `postalCode` string — A country-appropriate postal code representing where the package is shipping from.
    - `shipiumOriginId` string — The string used to identify the shipium originId.
    - `originId` string — The originId provided on the request. Null if no originId was provided.
    - `partnerOriginId` string — The partner-provided identifier (origin name) of the selected origin.
    - `originProcessingDays` number, double — The number of processing days configured for the given origin.
  - `requestDateOverride` string, date-time — Overrides the requestDate to a specific date & time from which the ship by and drop by date are calculated. ISO 8601 format
  - `desiredDeliveryDate` string, date-time — A valid date in ISO 8601 format representing the estimated delivery date to a customer configured in the call parameters for a given partner. Note that this value will be represented in the appropriate time zone for the customer delivery zip code.
  - `businessDaysOfTransit` integer — An integer number of business days by which the shipment must be delivered. Used as an alternative to desiredDeliveryDate and cannot be passed with desiredDeliveryDate.
  - `mustShipByDate` string, date — A date value specifying when the shipment needs to be shipped by (in the timezone of the FC from which it is shipping). Mutually exclusive with mustShipByBusinessDays and mustShipByCalendarDays.
  - `mustShipByBusinessDays` integer — An integer number of business days by which the shipment must be shipped from the FC. Mutually exclusive with mustShipByDate and mustShipByCalendarDays.
  - `mustShipByCalendarDays` integer — An integer number of calendar days by which the shipment must be shipped from the FC. Mutually exclusive with mustShipByDate and mustShipByBusinessDays.
  - `desiredDeliveryDateOptions` DesiredDeliveryDateOptions — Options for how the system will use the desiredDeliveryDate
    - `exactDateDelivery` boolean — This will restrict carrier selection to only use service methods that we have a high chance of making it there on time.
  - `carrierServiceMethodAllowList` string[] — A list of carrierServiceMethodId and/or carriers that should be considered for selection.
  - `shipmentParameters` SPShipmentParameters — Details of the shipment and its corresponding package and to/from addresses.
    - `shipFromAddress` SPAddress — The address of the location where the package is being delivered.
      - `street1` string — The first address line.
      - `street2` string — The second address line.
      - `city` string — The name of the city for the address.
      - `state` string — The name of the state for the address.
      - `countryCode` string, required — The ISO 3166-1 country code for the address.
      - `postalCode` string, required — A countryCode-appropriate postal code for the address.
      - `addressType` 'commercial' | 'residential' — The type of location for this address. Defaults to residential
    - `destinationAddress` SPAddress, required — The address of the location where the package is being delivered.
      - `street1` string — The first address line.
      - `street2` string — The second address line.
      - `city` string — The name of the city for the address.
      - `state` string — The name of the state for the address.
      - `countryCode` string, required — The ISO 3166-1 country code for the address.
      - `postalCode` string, required — A countryCode-appropriate postal code for the address.
      - `addressType` 'commercial' | 'residential' — The type of location for this address. Defaults to residential
    - `originId` string — The provided identifier of the origin or the shipium originId. This is exclusive with shipFromAddress and fulfillmentContextId.
    - `deliverySignatureOption` string — Defaults to None
    - `fulfillmentContext` string — A fulfillmentContext alias to use in the FulfillmentContextDetail search.
    - `fulfillmentType` string — Fulfillment methodology of the shipment.
    - `shipOption` string — A high-level shipping option shown to or selected by a customer.
    - `testMode` boolean — Indicates that a test shipment will be created with carriers and service methods considered in test mode.
    - `labelToDockDoorHours` number, double — An override for the origin config of the estimated time in hours between a label being printed and the shipment reaching the dock door.
  - `shipByDate` string, date-time, required — The date by which Shipium recommends shipping this customer’s package from the specified fulfillment center, represented in ISO-8601 format.
  - `fcDropByDate` string, date-time, required — The date by which Shipium recommends sending this customer’s shipment request to the specified fulfillment center, represented in ISO-8601 format.
  - `estimateSource` 'PartnerProvided' | 'ShipiumCalculated' | 'CarrierProvided' | 'Unknown', required — The source (ShipiumGenerated, PartnerProvided, or CarrierDefault) used to generate the estimate.
  - `estimatedTransitDays` integer, required — The number of transit days between the desired delivery date and the estimated ship by date.
  - `referenceIdentifier` string — Reference external identifier that is used for reporting purposes.
  - `partnerReferenceIdentifier` string — Reference external identifier explicitly provided by the partner. Used for reporting purposes.
  - `partnerReferenceIdentifier2` string — Secondary reference external identifier explicitly provided by the partner. Used for reporting purposes.
  - `referenceIdentifiers` ReferenceIdentifier[] — Reference external identifiers that are used for reporting purposes.
    - `name` string
    - `value` string
  - `shipmentTags` string[] — Shipment tags echoed back from the request. Matches the shipmentTags field on the corresponding Carrier Selection API request and is used for downstream reporting.
  - `shipDateException` boolean — Indicates if a ship date calculation exception occurred.
  - `shipDateExceptionDetails` ShipmentDateException — Ship date calculation exception details.
    - `exceptions` ShipmentDateExceptionInfo[]
      - `exceptionType` 'ExactDeliveryDateNotSupported' | 'LateDeliveryDate' | 'ShipDateInPast' | 'ShipDateAfterMustShipBy' | 'FcDropByDateInPast' | 'EarlyDeliveryDate'
      - `exceptionDescription` string
    - `effectiveFcDropByDate` string, date-time
    - `effectiveShipByDate` string, date-time
    - `effectiveDeliveryDate` string, date-time

## Other responses

- `204` — No Shipment Planning result available.
- `400` — Invalid inputs were provided.
- `403` — Not authenticated / authorized via OAuth.

---

[API](https://skmtc.net/shipium/apis/shipium-api.md) · [All operations](https://skmtc.net/shipium/apis/shipium-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shipium/shipium-api/revisions/7ef5dbd6a025/schema)