SHshipium
shipmentPlanning

Shipment Planning API

Changed on

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

post/api/v1/deliveryexperience/shipmentPlanning

Request

Request body

requestDateOverridestring date-time

Overrides the requestDate to a specific date & time from which the ship by and drop by date are calculated. ISO 8601 format

desiredDeliveryDatestring

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.

businessDaysOfTransitinteger

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.

mustShipByDatestring 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.

mustShipByBusinessDaysinteger

An integer number of business days by which the shipment must be shipped from the FC. Mutually exclusive with mustShipByDate and mustShipByCalendarDays.

mustShipByCalendarDaysinteger

An integer number of calendar days by which the shipment must be shipped from the FC. Mutually exclusive with mustShipByDate and mustShipByBusinessDays.

deliveryWindowDaysinteger

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.

carrierServiceMethodAllowListstring[]

A list of carrierServiceMethodId and/or carriers that should be considered for selection.

referenceIdentifierstring

Reference external identifier that is used for reporting purposes.

partnerReferenceIdentifierstring

Reference external identifier explicitly provided by the partner. Used for reporting purposes.

partnerReferenceIdentifier2string

Secondary reference external identifier explicitly provided by the partner. Used for reporting purposes.

shipmentTagsstring[]

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.

Example request

{
  "requestDateOverride": "2019-10-31T00:00:00Z",
  "desiredDeliveryDate": "2020-04-20",
  "mustShipByDate": "2020-04-20",
  "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"
    },
    "originId": "\"origin-id-123\"",
    "deliverySignatureOption": "resident_signature",
    "shipOption": "Standard"
  }
}

Response

Shipment Planning successfully calculated.

shipmentPlanningIdstring 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.

requestDateOverridestring date-time

Overrides the requestDate to a specific date & time from which the ship by and drop by date are calculated. ISO 8601 format

desiredDeliveryDatestring 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.

businessDaysOfTransitinteger

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.

mustShipByDatestring 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.

mustShipByBusinessDaysinteger

An integer number of business days by which the shipment must be shipped from the FC. Mutually exclusive with mustShipByDate and mustShipByCalendarDays.

mustShipByCalendarDaysinteger

An integer number of calendar days by which the shipment must be shipped from the FC. Mutually exclusive with mustShipByDate and mustShipByBusinessDays.

carrierServiceMethodAllowListstring[]

A list of carrierServiceMethodId and/or carriers that should be considered for selection.

shipByDatestring date-time required

The date by which Shipium recommends shipping this customer’s package from the specified fulfillment center, represented in ISO-8601 format.

fcDropByDatestring 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 used to generate the estimate. One of PartnerProvided, ShipiumCalculated, CarrierProvided, or Unknown when the source could not be determined.

estimatedTransitDaysinteger required

The number of transit days between the desired delivery date and the estimated ship by date.

referenceIdentifierstring

Reference external identifier that is used for reporting purposes.

partnerReferenceIdentifierstring

Reference external identifier explicitly provided by the partner. Used for reporting purposes.

partnerReferenceIdentifier2string

Secondary reference external identifier explicitly provided by the partner. Used for reporting purposes.

shipmentTagsstring[]

Shipment tags echoed back from the request. Matches the shipmentTags field on the corresponding Carrier Selection API request and is used for downstream reporting.

shipDateExceptionboolean

Indicates if a ship date calculation exception occurred.

Example response

{
  "shipmentPlanningId": "b903b8b0-84b4-11ea-ab12-0800200c9a66",
  "shippingOrigin": {
    "countryCode": "US",
    "postalCode": "98101",
    "shipiumOriginId": "0b3d140a-525b-43a7-896c-cdc381580d62",
    "originId": "warehouse-west",
    "partnerOriginId": "warehouse-west",
    "originProcessingDays": 2.5
  },
  "requestDateOverride": "2019-10-31T00:00:00Z",
  "desiredDeliveryDate": "2020-04-20T00:00:00Z",
  "mustShipByDate": "2020-04-20",
  "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"
    },
    "originId": "\"origin-id-123\"",
    "deliverySignatureOption": "resident_signature",
    "shipOption": "Standard"
  },
  "shipByDate": "2020-04-13T00:00:00Z",
  "fcDropByDate": "2020-04-12T00:00:00Z",
  "estimateSource": "ShipiumCalculated",
  "estimatedTransitDays": 3
}

Changes

  • 3edfc3693c7bRevision changes
    • breaking

      the // request property's minLength was increased from 0 to 2

    • breaking

      the // request property's minLength was increased from 0 to 2

    • warning

      deleted the header request parameter X-DELEGATED-PARTNER-ID

    • warning

      the // request property's maxLength was set to 2

    • warning

      the // request property's maxLength was set to 2

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property