# About desired delivery dates

You can provide an optional desired delivery date, or DDD, in API calls to Shipium's [Carrier Selection](https://docs.shipium.com/docs/carrier-and-method-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](https://www.iso.org/iso-8601-date-and-time-format.html) (e.g., 2023-11-30T12:00:00Z). A carrier and shipping 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](https://docs.shipium.com/docs/desired-and-exact-delivery-dates#about-exact-delivery-dates) in your API call.

### Weekend and holiday delivery behavior

When your desired delivery date falls on a Saturday or Sunday, specific carrier selection behavior applies. Additionally, carrier holidays affect transit time calculations. For comprehensive guidance on weekend delivery configuration, holiday impacts, and how these interact with the `desiredDeliveryDate` parameter, see [Weekend and Holiday Delivery](https://docs.shipium.com/docs/weekend-and-holiday-delivery).

## 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](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-api) request within the shipment parameters: `MegaShipmentProcessCreate.shipmentParameters`.

```json
{
  "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",
    "timeInTransitSetting": "conservative" // optional field, will default to conservative
  },
  "ignoreUpgradeSpendLimits": true // optional field, will default to false
}
```

## 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 date.

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

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

## How time in transit estimations work with desired and exact delivery dates

The Shipium platform uses a time in transit (TNT) calculation as part of estimating how long a shipment will take to be delivered to a customer, starting from the point at which it is shipped from a facility. This is a critical component of how we provide an estimated delivery date, or EDD.

Shipium offers three options for calculating TNTs in order to suit your organization’s business needs best:

- **Shipium calculated (recommended).** Shipium uses proprietary machine learning (ML) models on top of our large pool of shipment data to provide our best delivery date estimate.
- **Partner (customer) overrides.** Your organization may have business reasons to choose your own provided TNT values for some of your shipping lanes, rather than utilizing Shipium’s calculated values.
- **Carrier defaults.** You can choose to use TNT values provided by your organization’s carriers, such as UPS or USPS.

If your network settings include using Shipium-calculated TNTs, you can choose from four settings to apply when the system evaluates your desired or exact delivery date:

- **Low risk of late deliveries.** If your organization prioritizes on-time delivery promises, you can utilize the _conservative_ or _very conservative_ setting to minimize the risk of late deliveries, with a reduced likelihood of downgraded shipments relative to the standard setting.
- **Cost-effective shipping.** If you are focused on optimizing shipping costs and are less concerned with late deliveries, the _aggressive_ setting will offer aggressive delivery timelines.
- **Balanced approach.** If your organization prefers a balance between delivery reliability and cost-effectiveness, you can rely on the _standard_ setting to achieve your goals.
- **Precise delivery timing.** In scenarios where precise delivery timing is crucial, you can specify _exact date delivery_. In scenarios where precise delivery timing is critical, we enable _exact date delivery_ for qualifying shipments.

# 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](https://www.fedex.com/en-us/shipping/home-delivery.html#customize).

You can elect to request a guaranteed delivery date when making a call to Shipium's [Carrier Selection](https://docs.shipium.com/docs/carrier-method-selection-label-single-call) 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.

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

## Request fields for API calls

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

| Request field | Details |
| --- | --- |
| `shipmentParameters.desiredDeliveryDate` | **Type:** String<br>**Example:**`2019-10-31T20:00:00Z`<br>**Description:** The string representation of either an [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) date or a local date for desired delivery: `yyyy-mm-dd`. The date or date-time the package is intended to arrive to the customer. This is used to determine the most appropriate service method when generating a label. |
| `shipmentParameters.desiredDeliveryDateOptions.exactDateDelivery` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** If `true`, this instructs the carrier to deliver the package on the date provided in the `desiredDeliveryDate` field. |
| `shipmentParameters.desiredDeliveryDateOptions.guaranteedDateDelivery` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** If `true`, this indicates that your organization is willing to accept any applicable carrier date certain surcharge to the estimated label cost. Not all carriers support guaranteed date delivery. This restricts carrier selection to service methods that can support guaranteed date delivery. |
| `shipmentParameters.desiredDeliveryDateOptions.upgradeCostDeltaMax` | **Type:** Number (float)<br>**Description:** If set, this is the maximum amount of additional spend that your organization is willing to pay to upgrade a shipment to the desired delivery date (DDD) if the lowest cost carrier service method is unable to safely meet the DDD. This will override any Max Increase per Shipment value you have configured in the Shipium Console. |
| `shipmentParameters.desiredDeliveryDateOptions.currencyCode` | **Type:** String (enumeration)<br>**Example:**`usd`<br>**Description:** The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the `upgradeCostDeltaMax` |
| `shipmentParameters.desiredDeliveryDateOptions.timeInTransitSetting` | **Type:** String (enumeration)<br>**Values:**`very_conservative`, `conservative`, `standard`, `aggressive`<br>**Description:** Including this field in your API call will override any [time-in-transit setting configuration](https://docs.shipium.com/docs/time-in-transit-estimations), on a per shipment basis. These settings refer to Shipium-calculated time-in-transit (TNT) values. |
| `shipmentParameters.ignoreUpgradeSpendLimits` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** If `true`, this indicates that this shipment can ignore all of your organization's configured upgrade limits for the potential upgrade required to deliver the shipment by the desired delivery date. |