Desired Delivery Date

The desired delivery date enables you to make a call to carrier selection (whether getting a label or not) and optionally provide a desiredDeliveryDate in the API call. The desiredDeliveryDate is part of the shipmentParameters field. It takes an ISO8601 dateTime as its value. Based on that value, it chooses a carrier and ship method that will be able to hit or exceed that date.

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 that is provided.

In addition, there are additional parameters to control the behavior. These are described below.


This example shows how to handle DDD (Desired Delivery Date) 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 megamethod request within the shipment parameters: MegaShipmentProcessCreate.shipmentParameters

  "desiredDeliveryDate": "2022-03-30", // note: can be a full ISO-8601 date also.
  "ignoreUpgradeSpendLimits": true, // optional field, will default to false
  "shipOption": "DesiredDeliveryDate" // or null, or empty "", or not passed at all


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.


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

  • There is a new ship option in the shipOption enum: DesiredDeliveryDate.

    • The only shipOption that can be sent with a request that has a desired delivery date is DesiredDeliveryDate.
    • All other ship options will result in an error. You can also send null or no shipOption at all.