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 options call to see which advanced options your selected carrier provides.

The advanced_options object can be added to the shipments object in the create shipment call or the shipment object in the purchase label call.

Advanced Options Properties

Property	Type	Default Value	Description
`additional_handling`	boolean	`null`	Indicates the package requires special handling.
`ancillary_endorsements_option`	string	`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.
`bill_to_account`	string	`null`	The account number that will be charged when `bill_to_party` is set to `third_party`. Used in conjunction with `bill_to_country_code`, `bill_to_party`, and `bill_to_postal_code` fields for billing shipping costs to a third party.
`bill_to_country_code`	string	`null`	The two-letter country code associated with the account set in the `bill_to_account` field. Requires ISO 3166-1 alpha-2.
`bill_to_party`	string	`null`	Determines which party is paying for shipping costs. This field must be used in conjunction with the `bill_to_country_code`, `bill_to_postal_code`, and `bill_to_account` fields. Available values: `recipient` - Required for FedEx Ground Collect. `third_party` - Bill to an account that is not connected to ShipEngine. If `null`, shipping costs will be billed to the connected carrier account.
`bill_to_postal_code`	string	`null`	The postal code associated with the account set in the `bill_to_account` field. If using FedEx as the carrier, this field is validated.
`canada_delivered_duty`	string	`null`	Indicates that the shipper is pre-paying duties for USPS shipments to Canada. Use `sender_prepay` as the value.
`certificate_number`	string	`null`
`collect_on_delivery`	object	`null`	Defers payment to recipient when package is delivered. See Collect on Delivery page for details about using this property.
`contains_alcohol`	boolean	`false`	Indicates if the shipment contains alcohol.
`custom_field1`	string	`null`	<= 100 characters. A text field to store information about a shipment. Does not impact the carrier functionality.
`custom_field2`	string	`null`	<= 100 characters. A text field to store information about a shipment. Does not impact the carrier functionality.
`custom_field3`	string	`null`	<= 100 characters. A text field to store information about a shipment. Does not impact the carrier functionality.
`dangerous_goods`	boolean	`false`	Indicates if dangerous goods are present in the shipment. Please note that some carriers may also require additional dangerous goods properties added to the `packages.products` array. Review our Dangerous Goods page for more details.
`dangerous_goods_contact`	object	`null`	The recipient contact for the dangerous goods. Properties to include: `name` - string `phone` - string
`dangerous_goods_category`	string	`null`	This property is no longer part of the `advanced_options` object. It has been moved into the `dangerous_goods` object that is part of the `packages-products` array. See our Dangerous Goods page for more details about dangerous goods properties.
`delivered_duty_paid`	boolean	`false`	Indicates the shipment is DDP (that is, the shipper is paying the duties/taxes for the shipment rather than the recipient).
`dry_ice`	boolean	`false`	Indicates the shipment includes dry ice. Used in conjunction with the `dry_ice_weight` object.
`dry_ice_weight`	object	`null`	The weight added to the shipment by the dry ice. Properties (both required): `unit` - enumerated string, `pound` `ounce` `gram` `kilogram` `value` - decimal Please note, all dry ice weights will be converted and saved as ounces.
`fedex_freight`	object	`null`	Provide details for FedEx Freight services. Required fields: `shipper_load_and_count` - string `booking_confirmation` - string
`freight_class`	string	`null`	The NMFC freight class, used specifically for UPS Ground Freight pricing and in conjunction with `use_ups_ground_freight_pricing` property.
`invoice_number`	string	`null`
`license_number`	string	`null`
`non_machinable`	boolean	`false`	Indicates that the package cannot be processed through sorting machines. Primarily used for USPS shipments.
`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.
`origin_type`	enumerated string	`null`	Indicates if the package will be picked up or dropped off by the carrier. Values: `pickup` `dropoff`. See our PUDO guide for details about service points and supporting carriers.
`return_pickup_attempts`	string	`null`	Overrides the default number of attempts a supporting carrier will make to deliver a package. Valid values are `1` and `3`.
`saturday_delivery`	boolean	`false`	Indicates that the carrier should charge for delivery on Saturday for services that do not otherwise include saturday delivery.
`shipper_release`	boolean	`null`
`third-party-consignee`	boolean	`null`	Hides consignee-specific information on the commercial invoice for international shipments.
`use_ups_ground_freight_pricing`	boolean	`null`	Determines if UPS Ground Freight pricing will be used. Must use in conjunction with `freight_class` property.
`windsor_framework_details`	object	`null`	Object required when shipping from UK to Northern Ireland with supported carrier. 2 included properties: `movement_indicator` - indicates to the carrier and HMRC the type of movement for the shipment. Type: enumerated string, `c2c`, `b2c`, `c2b`, `b2b`. `not_at_risk` - indicates to the carrier and HMRC whether the shipment is or is not at risk of being resold into the EU. Type: boolean

Example Label Request

POST /v1/labels

This example is for 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
50
51
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",
      "email": "[email protected]",
      "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",
      "email": "[email protected]",
      "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.