Desired and Exact Delivery Dates
Pass optional desired and exact delivery dates in your calls to Shipium's APIs.
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 to23: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 cumulativeshipmentUpgradeSpend
) -
When making calls that use
desiredDeliveryDate
, you should not pass ashipOption
orbusinessDaysOfTransit
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.
Updated 1 day ago