Site Logo

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

Advanced Options Object

OptionNameDefault ValueDescription
Additional Handlingadditional_handlingnullIndicates the package requires special handling.
Bill To Partybill_to_partynullDetermines 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 Accountbill_to_accountnullThe account number that will be charged shipping costs when bill_to_party is third_party.
Bill To Postal Codebill_to_postal_codenullThe Postal Code associated with the bill_to_account. This will be validated by FedEx.
Bill To Country Codebill_to_country_codenullThe two-letter country code associated with the bill_to_account as it corresponds to ISO 3166-1 alpha-2.
Canada Delivered Dutycanada_delivered_dutynullIndicates that the shipper is pre-paying duties for USPS shipments to Canada.
sender_prepay
Contains Alcoholcontains_alcoholfalseIndicates if the shipment contains alcohol.
Delivered Duty Paiddelivered_duty_paidfalseIndicates that the shipper is pre-paying duty for the shipment.
Non Machinablenon_machinablefalseIndicates that the package cannot be processed through FedEx sorting machines.
Saturday Deliverysaturday_deliveryfalseIndicates that the carrier should charge for delivery on Saturday for services that do not otherwise include Saturday Delivery.
Dry Icedry_icefalseIndicates the shipment includes Dry Ice.
Dry Ice Weightdry_ice_weightsee weight object below
FedEx Freightfedex_freightnullObject 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 Consigneethird-party-consigneenullHides Consignee-specific information on the commercial invoice for international shipments.
Ancillary Endorsements Optionancillary_endorsements_optionnullIndicate 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 Classfreight_classnullSee our UPS Ground Freight article.
Custom Field 1custom_field1nullThis is a memo field and does not impact the carrier functionality.
Custom Field 2custom_field2nullThis is a memo field and does not impact the carrier functionality.
Custom Field 3custom_field3nullThis is a memo field and does not impact the carrier functionality.
Collect On Deliverycollect_on_deliverynullSee Collect on Delivery Collect on Delivery.
Return Pickup Attemptsreturn_pickup_attemptsnullOverrides the default number of attempts a supporting carrier will make to deliver a package. Valid values are 1 and 3.
Dangerous Goods Categorydangerous_goods_categorynullSee 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
SMS Tracking NotificationsNotificationsPhonenullWhen phone number is present, the carrier will send SMS tracking notifications. Supported by Royal Mail and Parcelforce Worldwide only.
Email Tracking NotificationsNotificationsEmailnullWhen email address is present, the carrier will send email tracking notifications. Supported by Royal Mail and Parcelforce Worldwide only.

Weight Object

PropertyDescription
unitenumerated string, required
valuedecimal, 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.