About desired delivery dates

You can provide an optional desired delivery date, or DDD, in API calls to Shipium's Carrier Selection service, whether getting a label or not. The desiredDeliveryDate is part of the shipmentParameters field. The DDD can be passed in a YYYY-MM-DD date-only format (e.g., 2023-11-30) or in the ISO-8601 date and time format (e.g., 2023-11-30T12:00:00Z). A carrier and ship method that can hit or exceed the DDD value will be selected during the carrier selection process.

The desiredDeliveryDate must be a date that is both:

• in the future relative to the time at which the call is made, and
• later than the shippedDateTime parameter, if it is provided.

Additional parameters that control the behavior are described below. For a more precise desired delivery date option, you can include an exact delivery date in your API call.

Example

This example shows how to handle DDD when you want a package to be delivered to a customer by a certain date. This may upgrade or downgrade the package, when appropriate.

The following can be added to the shipment parameters when creating a shipment with ShipmentParameters or to the Carrier and Method Selection & Shipment Label request within the shipment parameters: MegaShipmentProcessCreate.shipmentParameters.

{
  "desiredDeliveryDate": "2022-03-30", // note: can be a full ISO-8601 date also ("2022-03-30T12:00:00Z")
  "desiredDeliveryDateOptions": {
    "exactDateDelivery": false, // optional field, will default to false
    "upgradeCostDeltaMax": 0,
    "currencyCode": "usd"
  },
  "ignoreUpgradeSpendLimits": true, // optional field, will default to false
}

🚧

About the date

The desired delivery date will take the timestamp into account. If you do not care what time of day the package is delivered, you can pass just the YYYY-MM-DD date and we will automatically translate this to 23:59:59 on the date specified, in the timezone of the destination.

Notes

• Ignoring the upgrade spend limits will ignore all three varieties of limits that you can set on upgrades (totalUpgradeCostTolerance, upgradeOverCheapestCostTolerance, and the cumulative shipmentUpgradeSpend).

• When making calls that use desiredDeliveryDate, you should not pass a shipOption or businessDaysOfTransit value.

About exact delivery dates

If you're using desired delivery dates in your calls to Shipium's Carrier Selection APIs, you can increase the precision of your delivery request via the exact delivery date mechanism. Specifying an exact delivery date in your call request results in selection of the service method that will meet the DDD included in your request exactly, without constraints around cost upgrades. For example, if you request an exact delivery date, a more expensive service method could be chosen during Carrier Selection to more precisely meet your requested delivery date.

If you prefer to have more restrictive cost constraints and have more flexibility in the delivery date, you would not enable exact delivery date as a desired delivery date option.

Example

This example shows how to handle exact delivery date when you want a package to be delivered to a customer precisely by a certain date. This may upgrade or downgrade the package, when appropriate.

The following can be added to the shipment parameters when creating a shipment with ShipmentParameters or to the Carrier and Method Selection & Shipment Label request within the shipment parameters: MegaShipmentProcessCreate.shipmentParameters.

{
"desiredDeliveryDate": "2024-08-24T23:59:59-04:00",
"desiredDeliveryDateOptions": {
    "exactDateDelivery": true, // optional field, will default to false
    "upgradeCostDeltaMax": 2.50,
    "currencyCode": "usd"
  }
}

Notes

• When the exactDateDelivery field value is set to TRUE, all carriers and service methods that are unable to deliver on the DDD will be filtered out and not considered during carrier selection. This may result in increased HTTP 400 error responses (e.g., Could not find a carrier to fulfill the request: No service methods found).
• In the event that there is no eligible service method to meet the DDD, Shipium recommends one of two actions:
  • Resend your request with a modified DDD (e.g., +1 day).
  • Resend your request with exactDateDelivery set to FALSE, applying DDD logic but not requesting an exact delivery date.

About guaranteed delivery dates

Guaranteed delivery date is a service offered by some carriers that ensures a shipment's delivery on a certain date. For example, FedEx provides the guaranteed delivery date option through the FedEx Home Delivery® ground shipping service.

You can elect to request a guaranteed delivery date when making a call to Shipium's Carrier Selection service, whether getting a label or not. Carriers and service methods that do not support guaranteed date delivery will be eliminated from potential selection.

Example

This example shows how to handle the guaranteed delivery date request when you want a package to be delivered to a customer on a specific date. This may upgrade or downgrade the package, when appropriate.

The following can be added to the shipment parameters when creating a shipment with ShipmentParameters or to the Carrier and Method Selection & Shipment Label request within the shipment parameters: MegaShipmentProcessCreate.shipmentParameters.

{
  "desiredDeliveryDate": "2022-03-30", // note: can be a full ISO-8601 date also ("2022-03-30T12:00:00Z")
  "desiredDeliveryDateOptions": {
    "guaranteedDateDelivery": true
  }
}

Notes

• When the guaranteedDateDelivery field value is set to TRUE, all carriers and service methods that do not support guaranteed date delivery will be filtered out and not considered during carrier selection.

Request fields for API calls

The following table provides optional shipment parameter fields that can be included when calling Shipium's APIs.

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support