About special processing properties for a shipment

In certain cases, you may need special handling for a given shipment. In that case, there are several options you can specify as part of the Shipment entity, or when using the Carrier and Method Selection & Shipment Label API single call.

This document provides instructions for designating a shipment for:

Delivery instructions
Required delivery signature
Desktop delivery request
Saturday delivery request

For guidance on specifying shipment contents as a special designation, see the following documents:

Special processing and accessorial options

This table shows the optional special processing fields you can include in shipmentParameters, or in multiParcelShipmentParameters for multi-parcel shipments.

Request field	Details
`deliveryNote`	Type: String Description: Free-text delivery instructions for the carrier, such as where to leave the package. The note is sent only to carriers that accept delivery notes, and some carriers shorten it or remove characters to meet their own requirements. Note: Because support varies by carrier, use `deliveryNote` for helpful guidance rather than instructions a delivery must follow. For structured instructions such as leave at door, see `lastMileDeliveryOptions`.
`deliverySignatureOption`	Type: String (enumeration) Values: `none` (default), `signature`, `resident_signature`, `adult_signature`, `adult_resident_signature` Description: If you pass an optional `deliverySignatureOption`, its value is used to select only ship methods that support the specified delivery confirmation type. If you do not need a resident specifically, use `signature`, which is the most broadly supported across carriers. Note: Carrier support for individual values may vary; refer to your carrier's specific configuration or confirm support with your Shipium contact.
`desktopDelivery`	Type: Boolean Values: `true` or `false` (default) Description: Requests delivery to the recipient's desk or office rather than a mailroom or loading dock. This is a strict filter: when `true`, only carrier service methods that support desktop delivery are considered during carrier selection. If no supporting service method serves the shipment's lane, no service method is selected and no label is created: the Carrier and Method Selection & Shipment Label API call returns an HTTP 400 error, and a carrier selection request returns a `no_decision` status. Note: Desktop delivery is supported by a limited set of carrier service methods. Confirm availability for your lanes with your Shipium contact.
`lastMileDeliveryOptions`	Type: Object Description: Structured last-mile handling instructions, used by a limited set of carriers. Carriers that don't support these options don't receive them. This object applies to single-parcel shipments only; it isn't applied to multi-parcel shipments. It contains the following fields: `deliveryInstruction`: `LEAVE_AT_DOOR` or `MEET_AT_DOOR`; how the carrier completes delivery `undeliverableInstruction`: `LEAVE_AT_DOOR`, `RETURN`, or `DESTROY`; what the carrier does when the package can't be delivered `tip`: an object with `tipType` (`fixed` or `percentage`), `tipValue`, and `currencyCode` (an uppercase ISO 4217 code, such as `USD`). `tipType` is required when `tip` is included. Note: Set `tipValue` to the tip amount you want the carrier to receive. If a carrier doesn't support the instruction value you send, it may apply a different instruction that it does support. Confirm carrier support with your Shipium contact.
`saturdayDelivery`	Type: Boolean Values: `true` or `false` Description: This is a strict filter for Saturday-only services. For flexible weekend delivery, consider `desiredDeliveryDate`. Some carrier service methods deliver on Saturday for free, whereas some charge an additional fee for Saturday delivery. If you do not want to incur extra charges for Saturday delivery, this flag should be set to `false`, which is the default setting. Service methods that deliver for free on Saturday will still be considered during carrier selection. However, if you are willing to incur more cost and upgrade the carrier service method to meet a Saturday delivery, you can set this flag to `true`. If this flag is `true`, only carrier service methods that can deliver on Saturday will be considered. All other service methods will be filtered out of carrier selection. Note: Setting this flag to `true` does not guarantee a Saturday delivery, which is dependent upon the carrier. If you have included a desired delivery date (DDD) of Saturday or Sunday, setting this flag to `false` does not impact the DDD for a Saturday delivery.

Saturday delivery

Saturday delivery can be requested using two different approaches, each with distinct behavior:

Option 1. Saturday Delivery Flag

"saturdayDelivery": true

When to use. You require delivery specifically on Saturday.
Behavior. Returns only services that explicitly support Saturday delivery to your destination
Result. May return fewer options, all of them Saturday-capable services

Option 2. Desired Delivery Date

"desiredDeliveryDate": "2024-03-16"  // A Saturday

When to use. You want delivery by Saturday (weekend timeline).
Behavior. Returns services that can deliver on or before the specified Saturday
Result. More shipping options, including Friday delivery that meets your timeline

💡
Tip
Use the Saturday delivery flag only when Saturday is a hard requirement. For flexible weekend delivery, use desiredDeliveryDate for more options. You can find information in the desired delivery date documentation.

📘
Comprehensive weekend and holiday guidance
For detailed information about how Saturday delivery interacts with desired delivery dates, weekend transit day calculations, carrier holiday impacts, and common troubleshooting scenarios, see Weekend and Holiday Delivery.

Resources

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