Advanced Options

Many carriers support advanced options, such as the ability to ship alcohol, bill to the receiving party, request money on delivery, and many others. A carrier will generally support only a few of all possible advanced options. Use the List Carrier Advanced Options call to see which advanced options your selected carrier provides.

The advanced_options object can be added to the shipments array in the Create Shipment call or the shipment object in the Purchase Label call.

Advanced Options Object

Advanced Option	Default Value	Description
`additional_handling`	`null`	Indicates the package requires special handling.
`bill_to_party`	`null`	Determines which party is paying for shipping costs. If `null`, shipping costs will be billed to the connected carrier account. Available values: `recipient` - Required for FedEx Ground Collect. `third_party` - Bill to an account that is not connected to ShipEngine. When billing to a third party, you may not see receive rates for the shipment. This field must be used in conjunction with the `bill_to_country_code`, `bill_to_postal_code`, and `bill_to_account` fields.
`bill_to_account`	`null`	The account number that will be charged shipping costs when `bill_to_party` is set to `third_party`.
`bill_to_postal_code`	`null`	The postal code associated with the `bill_to_account` number. This will be validated by FedEx.
`bill_to_country_code`	`null`	The two-letter country code associated with the `bill_to_account`. Requires using ISO 3166-1 alpha-2.
`canada_delivered_duty`	`null`	Indicates that the shipper is pre-paying duties for USPS shipments to Canada. Use `sender_prepay` as the value.
`contains_alcohol`	`false`	Indicates if the shipment contains alcohol.
`delivered_duty_paid`	`false`	Indicates the shipment is DDP (that is, the shipper is pre-paying duties for the shipment).
`non_machinable`	`false`	Indicates that the package cannot be processed through sorting machines.
`saturday_delivery`	`false`	Indicates that the carrier should charge for delivery on Saturday for services that do not otherwise include saturday delivery.
`dry_ice`	false	Indicates the shipment includes dry ice.
`dry_ice_weight`	`null`	The weight added to the shipment by the dry ice. Properties: `unit` - enumerated string, required `value` - decimal, required Please note, all dry ice weights will be converted and saved as ounces.
`fedex_freight`	`null`	Provide details for FedEx Freight services. Required fields: `shipper_load_and_count` - string `booking_confirmation` - string
`third-party-consignee`	`null`	Hides consignee-specific information on the commercial invoice for international shipments.
`ancillary_endorsements_option`	`null`	Indicate the endorsement, if not specified on the carrier account. Available values: `AddressServiceRequested` - Request Address Correction when possible. If undeliverable, return to sender. `ForwardingServiceRequested` - Request forwarding when possible. `ChangeServiceRequested` - Request Address Correction when possible. If undeliverable, either the new address or the reason a shipment is undeliverable is returned. `ReturnServiceRequested` - Provides address correction services and always returns the piece.
`freight_class`	`null`	See our UPS Ground Freight article for details.
`custom_field1`	`null`	This is a memo field and does not impact the carrier functionality.
`custom_field2`	`null`	This is a memo field and does not impact the carrier functionality.
`custom_field3`	`null`	This is a memo field and does not impact the carrier functionality.
`collect_on_delivery`	`null`	See Collect on Delivery for more details.
`return_pickup_attempts`	`null`	Overrides the default number of attempts a supporting carrier will make to deliver a package. Valid values are `1` and `3`.
`dangerous_goods`	`false`	Indicates if dangerous goods are present in the shipment.
`dangerous_goods_contact`	`null`	The recipient contact for the dangerous goods. Fields: `name` - string `phone` - string
`dangerous_goods_category`	`null`	See our Dangerous Goods article for details about how to ship dangerous goods that are normally restricted from mail, like lithium ion batteries. This is currently supported for: DHL eCommerce Mondial Relay New Zealand Post TNT AU USPS
`NotificationsPhone`	`null`	The carrier will send SMS tracking notifications if phone number is present. Supported by Royal Mail and Parcelforce Worldwide only.
`NotificationsEmail`	`null`	The carrier will send email tracking notifications if email address is present. Supported by Royal Mail and Parcelforce Worldwide only.
`windsor_framework_details`	`null`	Object required when shipping from UK to Northern Ireland (must ship with supported carrier). 2 available fields: `movement_indicator` - indicates to the carrier and HMRC the type of movement for the shipment. Type: enumerated string, available values: `c2c`, `b2c`, `c2b`, `b2b`. `not_at_risk` - indicates to the carrier and HMRC that the shipment is not-at-risk. Type: boolean

Example

POST /v1/labels

This example includes a shipment that contains alcohol. For alcohol shipments, many carriers also require a special Delivery Confirmation. This example uses UPS as the carrier, since they support the adult_signature delivery confirmation and alcohol delivery advanced option.

The example request body will include shipment.advanced_options and shipment.confirmation:

1
2
3
4
5
6
{
  "advanced_options": {
    "contains_alcohol": "true"
  },
  "confirmation": "adult_signature"
}

Request Body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "shipment": {
    "service_code": "ups_3_day_select",
    "ship_to": {
      "name": "Amanda Miller",
      "phone": "555-555-5555",
      "address_line1": "525 S Winchester Blvd",
      "city_locality": "San Jose",
      "state_province": "CA",
      "postal_code": "95128",
      "country_code": "US",
      "address_residential_indicator": "yes"
    },
    "ship_from": {
      "company_name": "Example Corp.",
      "name": "John Doe",
      "phone": "111-111-1111",
      "address_line1": "4009 Marathon Blvd",
      "address_line2": "Suite 300",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US",
      "address_residential_indicator": "no"
    },
    "confirmation": "adult_signature",
    "advanced_options": {
      "contains_alcohol": "true"
    },
    "insurance_provider": "none",
    "total_weight": {
      "value": 3.0,
      "unit": "pound"
    },
    "packages": [
      {
        "weight": {
          "value": 3.0,
          "unit": "pound"
        }
      }
    ]
  }
}

The response will not include any additional fields indicating the advanced option that was set or the confirmation type. However, this information is sent to the carrier in the label request and in most cases should be indicated on the resulting label.