About desired delivery date

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.

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 with Label Single Call (megamethod) 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")
  "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 date

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

You can elect to request an exact 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 exact date delivery will be eliminated from potential selection.

Example

This example shows how to handle the exact 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 with Label Single Call (megamethod) 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": true
  }
}

Notes

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

FAQ

Q: Can I include a desired delivery date (DDD) in addition to passing a ship option when using the all-in-one shipment and label method?

A: Yes. For example, shipOption: standard, desiredDeliveryDate: 2023-11-15 limits the carrier selection search to only those methods that are marked as standard and for which the DDD of 2023-11-15 can be met. If the DDD of 2023-11-15 cannot be met, Shipium will return the cheapest service method on 2023-11-16, and so on.