Advanced Options

Many carriers support "Advanced Options", such as the ability to ship alcohol, bill to the receiving party, request money on delivery, or many others. You will need to see the supported options from each carrier by using the List Carrier Advanced Options.

Advanced Options Object

Option	Name	Default Value	Description
Additional Handling	`additional_handling`	`null`	Indicates the package requires special handling.
Bill To Party	`bill_to_party`	`null`	Determines which party is paying for shipping costs. If `null`, shipping costs will be billed to the connected carrier account. `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 rates returned from ShipEngine API. 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	`bill_to_account`	`null`	The account number that will be charged shipping costs when `bill_to_party` is `third_party`.
Bill To Postal Code	`bill_to_postal_code`	`null`	The Postal Code associated with the `bill_to_account`. This will be validated by FedEx.
Bill To Country Code	`bill_to_country_code`	`null`	The two-letter country code associated with the `bill_to_account` as it corresponds to ISO 3166-1 alpha-2.
Canada Delivered Duty	`canada_delivered_duty`	`null`	Indicates that the shipper is pre-paying duties for USPS shipments to Canada. `sender_prepay`
Contains Alcohol	`contains_alcohol`	`false`	Indicates if the shipment contains alcohol.
Delivered Duty Paid	`delivered_duty_paid`	`false`	Indicates that the shipper is pre-paying duty for the shipment.
Non Machinable	`non_machinable`	`false`	Indicates that the package cannot be processed through FedEx sorting machines.
Saturday Delivery	`saturday_delivery`	`false`	Indicates that the carrier should charge for delivery on Saturday for services that do not otherwise include Saturday Delivery.
Dry Ice	`dry_ice`	false	Indicates the shipment includes Dry Ice.
Dry Ice Weight	`dry_ice_weight`	see weight object below
FedEx Freight	`fedex_freight`	`null`	Object to provide details for FedEx Freight services. `shipper_load_and_count` - String required by FedEx for Freight shipments. `booking_confirmation` - String required by FedEx for Freight shipments.
Third Party Consignee	`third-party-consignee`	`null`	Hides Consignee-specific information on the commercial invoice for international shipments.
Ancillary Endorsements Option	`ancillary_endorsements_option`	`null`	Indicate the endorsement, if not specified on the carrier account. `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	`freight_class`	`null`	See our UPS Ground Freight article.
Custom Field 1	`custom_field1`	`null`	This is a memo field and does not impact the carrier functionality.
Custom Field 2	`custom_field2`	`null`	This is a memo field and does not impact the carrier functionality.
Custom Field 3	`custom_field3`	`null`	This is a memo field and does not impact the carrier functionality.
Collect On Delivery	`collect_on_delivery`	`null`	See Collect on Delivery Collect on Delivery.
Return Pickup Attempts	`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 Category	`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

Weight Object

Property	Description
`unit`	enumerated string, required
`value`	decimal, required

Example

POST /v1/labels

For this example, we're going to send Amanda Miller some wine. Since we're shipping alcohol, we're also going to have to use a special Delivery Confirmation as well. We'll be using UPS as the carrier, since they support adult_signature and alcohol delivery.

We added the dictionary shipment.advanced_options and string shipment.confirmation:

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

Example Request

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"
        }
      }
    ]
  }
}

Example Response

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
{
  "label_id": "se-421210",
  "status": "completed",
  "shipment_id": "se-2126974",
  "ship_date": "2019-07-25T05:00:00.000Z",
  "created_at": "2019-07-25T15:24:46.657Z",
  "shipment_cost": {
    "currency": "usd",
    "amount": 29.25
  },
  "insurance_cost": {
    "currency": "usd",
    "amount": 0.0
  },
  "tracking_number": "1Z28A1R9A713398376",
  "is_return_label": false,
  "is_international": false,
  "batch_id": "",
  "carrier_id": "se-123890",
  "service_code": "ups_3_day_select",
  "package_code": "package",
  "voided": false,
  "label_format": "pdf",
  "label_layout": "4x6",
  "trackable": false,
  "carrier_code": "ups",
  "tracking_status": "unknown",
  "label_download": {
    "pdf": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.pdf",
    "png": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.png",
    "zpl": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.zpl",
    "href": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.pdf"
  },
  "form_download": null,
  "insurance_claim": null
}

Next Step: Ship It!

You can now print your label and ship it! Your label can be found by navigating to label_download.href.