Options

Shipments can have a variety of additional options which you can specify when creating a shipment. The Options object can be populated with the keys below.

Carrier specific support for each option is added as needed. To request support for a specific carrier option, please contact our Support team.

Endpoints

POST

/shipments

Options object

additional_handling

boolean

Setting this option to true, will add an additional handling charge. An Additional Handling charge may be applied to the following:

Any article that is encased in an outside shipping container made of metal or wood.
Any item, such as a barrel, drum, pail or tire, that is not fully encased in a corrugated cardboard shipping container.
Any package with the longest side exceeding 60 inches or its second longest side exceeding 30 inches.
Any package with an actual weight greater than 70 pounds.

address_validation_level

string

Setting this option to "0" will allow the minimum amount of address information to pass the validation check. Only for USPS postage.

alcohol

boolean

Set this option to true if your shipment contains alcohol.

UPS - only supported for U.S. domestic shipments
FedEx - only supported for U.S. domestic shipments
Canada Post - Requires adult signature 19 years or older. If you want adult signature 18 years or older, instead usedelivery_confirmation: "ADULT_SIGNATURE"

by_drone

boolean

Setting this option to true will indicate to the carrier to prefer delivery by drone, if the carrier supports drone delivery.

carbon_neutral

boolean

Setting this to true will add a charge to reduce carbon emissions by carriers who support this option. Alternatively, see Carbon Offset which is provided by EasyPost and works with all carriers.

carrier_notification_email

string

Assign an email address to receive carrier notifications.

carrier_notification_sms

string

Assign a phone number to receive carrier notifications.

cod_amount

string

Adding an amount will have the carrier collect the specified amount from the recipient.

cod_method

string

Method for payment. Possible values:

"CASH"
"CHECK"
"MONEY_ORDER"

cod_address_id

string

The ID of the Address to which the C.O.D payment should be returned. Defaults to the origin address. Only available on FedEx shipments.

content_description

string

A description of the content of the shipment.

currency

string

Which currency this shipment will show for rates if carrier allows.

delivery_confirmation

string

If you want to request a signature, you can pass "ADULT_SIGNATURE" or "SIGNATURE". You may also request "NO_SIGNATURE" to leave the package at the door. "NO_SIGNATURE" is equivalent to releasing liability. Some options may be limited for international shipments. Carrier specific delivery confirmation options are listed below:

FedEx

"INDIRECT_SIGNATURE" - Requires the signature of someone at the delivery address or from somebody nearby, such as a neighbor.
"SERVICE_DEFAULT" - Attempts to set the signature requirements based on the shipment details and service level.

USPS

"ADULT_SIGNATURE_RESTRICTED" - Requires the signature of the specific addressee, or authorized agent, who is 21 years of age or older.
"SIGNATURE_RESTRICTED" - Requires the signature of the specified addressee, or authorized agent.

Canada Post

"DO_NOT_SAFE_DROP" - Tells the carrier to not hide the package ("safe drop").

GSO

"STANDARD_SIGNATURE"

DHL Express

"SIGNATURE" - DHL Express Direct Signature
"NO_SIGNATURE" - DHL Express Signature Release

delivery_min_datetime

string

The earliest a package should be delivered. Supported carriers vary.

delivery_max_datetime

string

The latest a package should be delivered. Supported carriers vary.

dropoff_type

string

Method the customer will use to transfer the package to the carrier. Supported dropoff types and their corresponding carrier dropoff codes are below:

FedEx

"REGULAR_PICKUP" - Customer to transfer package during regular pickup (default)
"SCHEDULED_PICKUP" - Customer to transfer package during scheduled pickup
"RETAIL_LOCATION" - Customer to transfer package at FedEx retail location
"STATION" - "STATION"
"DROP_BOX" - Customer to use carrier drop box for package transfer

dry_ice

boolean

Package contents contain dry ice.

UPS - Need dry_ice_weight to be set
UPS MailInnovations - Need dry_ice_weight to be set
FedEx - Need dry_ice_weight to be set

dry_ice_medical

boolean

If the dry ice is for medical use, set this option to true.

UPS - Need dry_ice_weight to be set
UPS MailInnovations - Need dry_ice_weight to be set

dry_ice_weight

string

Weight of the dry ice in ounces.

UPS - Need dry_ice_weight to be set
UPS MailInnovations - Need dry_ice_weight to be set
FedEx - Need dry_ice_weight to be set

duty_payment

object

Setting duty_payment type to bill the correct account for purchasing postage. This option is only available with FedEx and UPS.

type - (string) Supported values:
- "THIRD_PARTY"
- "RECEIVER"
account - (string) Setting account number
country - (string) Setting country code that the account is based in
postal_code - (string) Setting postal code that the account is based in

endorsement

string

Possible values:

"ADDRESS_SERVICE_REQUESTED"
"FORWARDING_SERVICE_REQUESTED"
"CHANGE_SERVICE_REQUESTED"
"RETURN_SERVICE_REQUESTED"
"LEAVE_IF_NO_RESPONSE"

end_shipper_id

string

Specify the responsible EndShipper for the shipment by passing in an EndShipper ID.

freight_charge

double

Additional cost to be added to the invoice of this shipment. Only applies to UPS currently.

handling_instructions

string

This is to designate special instructions for the carrier like "Do not drop!".

hazmat

string

Used to identify the type of hazardous materials (HAZMAT) or dangerous goods being shipped. Unidentified HAZMAT can introduce risk to human safety, property and expose the shipper to civil penalties, especially for packages that travel via air. Each carrier may have a different way of identifying HAZMAT and rates will only be retuned for carriers that support the type designated. Refer to carrier documentation to determine how to identify HAZMAT types and for complete rules and regulations.

FedEx and DHL eCommerce

"PRIMARY_CONTAINED": Primary Contained
"PRIMARY_PACKED": Primary Packed
"PRIMARY": Primary
"SECONDARY_CONTAINED": Secondary Contained
"SECONDARY_PACKED": Secondary Packed
"SECONDARY": Secondary
"ORMD": Other Regulated Materials—Domestic
"LITHIUM": Lithium

FedEx, DHL eCommerce, and USPS

"LIMITED_QUANTITY": Limited Quantity Ground Package

USPS: See EasyPost's USPS HazMat Guide and USPS Pub. 52 for complete regulations.

"AIR_ELIGIBLE_ETHANOL": Air Eligible Ethanol Package
"CLASS_1": Class 1 - Toy Propellant/Safety Fuse Package
"CLASS_3": Class 3 - Package
"CLASS_7": Class 7 - Radioactive Materials Package
"CLASS_8_CORROSIVE": Class 8 - Corrosive Materials Package
"CLASS_8_WET_BATTERY": Class 8 - Nonspillable Wet Battery Package
"CLASS_9_NEW_LITHIUM_INDIVIDUAL": Class 9 - Lithium Battery Marked - Ground Only Package
"CLASS_9_USED_LITHIUM": Class 9 - Lithium Battery - Returns Package
"CLASS_9_NEW_LITHIUM_DEVICE": Class 9 - Lithium batteries, marked package
"CLASS_9_DRY_ICE": Class 9 - Dry Ice Package
"CLASS_9_UNMARKED_LITHIUM": Class 9 - Lithium batteries, unmarked package
"CLASS_9_MAGNETIZED": Class 9 - Magnetized Materials Package
"DIVISION_4_1": Division 4.1 - Mailable flammable solids and Safety Matches Package
"DIVISION_5_1": Division 5.1 - Oxidizers Package
"DIVISION_5_2": Division 5.2 - Organic Peroxides Package
"DIVISION_6_1": Division 6.1 - Toxic Materials Package (with an LD50 of 50 mg/kg or less)
"DIVISION_6_2": Division 6.2
"EXCEPTED_QUANTITY_PROVISION": Excepted Quantity Provision Package
"GROUND_ONLY": Ground Only
"ID8000": ID8000 Consumer Commodity Package
"LIGHTERS": Lighters Package
"SMALL_QUANTITY_PROVISION": Small Quantity Provision Package

hold_for_pickup

boolean

Package will wait at carrier facility for pickup.

incoterm

string

Incoterm negotiated for shipment. Supported values:

"CFR"
"CIF"
"CIP"
"CPT"
"DAT"
"DAP"
"DDP"
"EXW"
"FAS"
"FCA"
"FOB"

Setting this value to anything other than "DDP" will pass the cost and responsibility of duties on to the recipient of the package(s), as specified by Incoterms rules.

invoice_number

string

This will print an invoice number on the postage label.

label_date

string

Set the date that will appear on the postage label. Accepts ISO 8601-formatted string including time zone offset. EasyPost stores all dates as UTC time.

label_format

string

Supported label formats:

"PNG"
"PDF"
"ZPL"
"EPL2"

"PNG" is the only format that allows for conversion.

live_animal

string

USPS only option - specifies the type of live animal being shipped. Supported values:

"DAY_OLD_POULTRY": Used to ship day-old poultry with USPS.

machinable

boolean

Whether or not the parcel can be processed by the carriers equipment

merchant_id

string

This is a required field for DHL eCommerce shipments and should be the merchant's name. It will be displayed on the shipping label and associated with the shipment throughout transit.

payment

object

Specifies the payment method for billing the correct account when purchasing postage. Not all payment options are supported by all carriers. "SENDER" (default) billing is used if alternate billings are not supported by the partner platform. It is the shipper's responsibility to confirm with the carrier what billing options are available.

type - (string) Supported values:
- "SENDER" (default)
- "THIRD_PARTY"
- "RECEIVER"
- "COLLECT"
account - (string) Account number to be billed. Required if type is "RECEIVER" or "THIRD_PARTY".
country - (string) Country code of the billing account. Required if type is "THIRD_PARTY".
postal_code - (string) Postal code of the billing account. Required if type is "RECEIVER" or "THIRD_PARTY".

pickup_min_datetime

string

The earliest a package should be picked up. Supported carriers vary.

pickup_max_datetime

string

The latest a package should be picked up. Supported carriers vary.

print_custom_1

string

You can optionally print custom messages on labels. The locations of these fields show up on different spots on the carrier's labels.

print_custom_2

string

An additional message on the label. Same restrictions as print_custom_1.

print_custom_3

string

An additional message on the label. Same restrictions as print_custom_1

print_custom_1_barcode

boolean

Create a barcode for this custom reference if supported by carrier.

print_custom_2_barcode

boolean

Create a barcode for this custom reference if supported by carrier.

print_custom_3_barcode

boolean

Create a barcode for this custom reference if supported by carrier.

print_custom_1_code

string

Specify the type of print_custom_1.

FedEx

(null) - If print_custom_1_code is not provided it defaults to Customer Reference
PO - Purchase Order Number
DP - Department Number
RMA - Return Merchandise Authorization

UPS

AJ - Accounts Receivable Customer Account
AT - Appropriation Number
BM - Bill of Lading Number
9V - Collect on Delivery (COD) Number
ON - Dealer Order Number
DP - Department Number
3Q - Food and Drug Administration (FDA) Product Code
IK - Invoice Number
MK - Manifest Key Number
MJ - Model Number
PM - Part Number
PC - Production Code
PO - Purchase Order Number
RQ - Purchase Request Number
RZ - Return Authorization Number
SA - Salesperson Number
SE - Serial Number
ST - Store Number
TN - Transaction Reference Number
EI - Employer's ID Number
TJ - Federal Taxpayer ID Number

print_custom_2_code

string

See print_custom_1_code.

print_custom_3_code

string

See print_custom_1_code.

saturday_delivery

boolean

Set this value to true to make your shipment eligible for Saturday delivery.

special_rates_eligibility

string

This option enables the selection of the following USPS mail classes:

Media Mail - USPS.MEDIAMAIL
Library Mail - USPS.LIBRARYMAIL

To request rates for both classes simultaneously, input USPS.MEDIAMAIL,USPS.LIBRARYMAIL.
These mail classes are subject to restrictions and eligibility rules as outlined in the DMM .

smartpost_hub

string

You can use this to override the hub ID you have on your account.

smartpost_manifest

string

The manifest ID is used to group SmartPost packages onto a manifest for each trailer.

billing_ref

string

A reference ID for aggregating DHL eCommerce billing data.

certified_mail

boolean

Certified Mail provides the sender with a mailing receipt and, upon request, electronic verification that an article was delivered or that a delivery attempt was made.

registered_mail

boolean

Registered Mail is the most secure service that the USPS offers. It incorporates a system of receipts to monitor the movement of the mail from the point of acceptance to delivery.

registered_mail_amount

double

The value of the package contents

return_receipt

boolean

An electronic return receipt may be purchased at the time of mailing and provides a shipper with evidence of delivery (to whom the mail was delivered and date of delivery), and information about the recipient's actual delivery address. Only applies to the USPS.

Options Object

{
  "print_custom_1": "Custom label message",
  "currency": "USD",
  "print_custom": [
    {
      "value": "Custom label message"
    }
  ],
  "payment": {
    "type": "SENDER"
  },
  "date_advance": 0
}

Create a Shipment with Options

Any number of options can be specified during Shipment creation.

A Shipment object is immutable once created. All information must be provided during creation; it cannot be modified later.

POST /shipments

1curl -X POST https://api.easypost.com/v2/shipments \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "shipment": {
6      "to_address": {
7        "id": "adr_..."
8      },
9      "from_address": {
10        "id": "adr_..."
11      },
12      "parcel": {
13        "id": "prcl_..."
14      },
15      "options": {
16        "print_custom_1": "Custom label message"
17      }
18    }
19  }'

Response

1{
2  "created_at": "2024-01-24T00:05:54Z",
3  "is_return": false,
4  "messages": [],
5  "mode": "test",
6  "options": {
7    "print_custom_1": "Custom label message",
8    "currency": "USD",
9    "print_custom": [
10      {
11        "value": "Custom label message"
12      }
13    ],
14    "payment": {
15      "type": "SENDER"
16    },
17    "date_advance": 0
18  },
19  "reference": null,
20  "status": "unknown",
21  "tracking_code": null,
22  "updated_at": "2024-01-24T00:05:54Z",
23  "batch_id": null,
24  "batch_status": null,
25  "batch_message": null,
26  "customs_info": {
27    "id": "cstinfo_8a0e647447974eaf97d0d94fe660c888",
28    "object": "CustomsInfo",
29    "created_at": "2024-01-24T00:05:54Z",
30    "updated_at": "2024-01-24T00:05:54Z",
31    "contents_explanation": "",
32    "contents_type": "merchandise",
33    "customs_certify": true,
34    "customs_signer": "Steve Brule",
35    "eel_pfc": "NOEEI 30.37(a)",
36    "non_delivery_option": "return",
37    "restriction_comments": null,
38    "restriction_type": "none",
39    "mode": "test",
40    "declaration": null,
41    "customs_items": [
42      {
43        "id": "cstitem_34121009b24446eca08712c10b95ffb7",
44        "object": "CustomsItem",
45        "created_at": "2024-01-24T00:05:54Z",
46        "updated_at": "2024-01-24T00:05:54Z",
47        "description": "T-shirt",
48        "hs_tariff_number": "123456",
49        "origin_country": "US",
50        "quantity": 1,
51        "value": "10.0",
52        "weight": 5.0,
53        "code": "123",
54        "mode": "test",
55        "manufacturer": null,
56        "currency": null,
57        "eccn": null,
58        "printed_commodity_identifier": null
59      }
60    ]
61  },
62  "from_address": {
63    "id": "adr_57988df8ba4c11ee8d3bac1f6bc539ae",
64    "object": "Address",
65    "created_at": "2024-01-24T00:05:54+00:00",
66    "updated_at": "2024-01-24T00:05:54+00:00",
67    "name": "EasyPost",
68    "company": null,
69    "street1": "417 Montgomery Street",
70    "street2": "5th Floor",
71    "city": "San Francisco",
72    "state": "CA",
73    "zip": "94104",
74    "country": "US",
75    "phone": "4153334445",
76    "email": "support@easypost.com",
77    "mode": "test",
78    "carrier_facility": null,
79    "residential": null,
80    "federal_tax_id": null,
81    "state_tax_id": null,
82    "verifications": {}
83  },
84  "insurance": null,
85  "order_id": null,
86  "parcel": {
87    "id": "prcl_5e953fb53a5f4207b7d6ee32267d25cb",
88    "object": "Parcel",
89    "created_at": "2024-01-24T00:05:54Z",
90    "updated_at": "2024-01-24T00:05:54Z",
91    "length": 20.2,
92    "width": 10.9,
93    "height": 5.0,
94    "predefined_package": null,
95    "weight": 65.9,
96    "mode": "test"
97  },
98  "postage_label": null,
99  "rates": [
100    {
101      "id": "rate_caa4e8d8f0ae4a06b7ea79451886c781",
102      "object": "Rate",
103      "created_at": "2024-01-24T00:05:54Z",
104      "updated_at": "2024-01-24T00:05:54Z",
105      "mode": "test",
106      "service": "Express",
107      "carrier": "USPS",
108      "rate": "49.60",
109      "currency": "USD",
110      "retail_rate": "57.40",
111      "retail_currency": "USD",
112      "list_rate": "49.60",
113      "list_currency": "USD",
114      "billing_type": "easypost",
115      "delivery_days": null,
116      "delivery_date": null,
117      "delivery_date_guaranteed": false,
118      "est_delivery_days": null,
119      "shipment_id": "shp_ca70827221b04ad589f0d170ec933f52",
120      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
121    },
122    {
123      "id": "rate_c5c1761ec40244e3bb06e16e4bf84e27",
124      "object": "Rate",
125      "created_at": "2024-01-24T00:05:54Z",
126      "updated_at": "2024-01-24T00:05:54Z",
127      "mode": "test",
128      "service": "Priority",
129      "carrier": "USPS",
130      "rate": "7.33",
131      "currency": "USD",
132      "retail_rate": "15.20",
133      "retail_currency": "USD",
134      "list_rate": "10.89",
135      "list_currency": "USD",
136      "billing_type": "easypost",
137      "delivery_days": 2,
138      "delivery_date": null,
139      "delivery_date_guaranteed": false,
140      "est_delivery_days": 2,
141      "shipment_id": "shp_ca70827221b04ad589f0d170ec933f52",
142      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
143    },
144    {
145      "id": "rate_4f361f673c364f28bd4c8aa806c9a226",
146      "object": "Rate",
147      "created_at": "2024-01-24T00:05:54Z",
148      "updated_at": "2024-01-24T00:05:54Z",
149      "mode": "test",
150      "service": "GroundAdvantage",
151      "carrier": "USPS",
152      "rate": "6.79",
153      "currency": "USD",
154      "retail_rate": "13.15",
155      "retail_currency": "USD",
156      "list_rate": "9.41",
157      "list_currency": "USD",
158      "billing_type": "easypost",
159      "delivery_days": 3,
160      "delivery_date": null,
161      "delivery_date_guaranteed": false,
162      "est_delivery_days": 3,
163      "shipment_id": "shp_ca70827221b04ad589f0d170ec933f52",
164      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
165    },
166    {
167      "id": "rate_c201b421c0304e73a4320c240d3c206b",
168      "object": "Rate",
169      "created_at": "2024-01-24T00:05:54Z",
170      "updated_at": "2024-01-24T00:05:54Z",
171      "mode": "test",
172      "service": "First",
173      "carrier": "USPS",
174      "rate": "6.79",
175      "currency": "USD",
176      "retail_rate": "13.15",
177      "retail_currency": "USD",
178      "list_rate": "9.41",
179      "list_currency": "USD",
180      "billing_type": "easypost",
181      "delivery_days": 3,
182      "delivery_date": null,
183      "delivery_date_guaranteed": false,
184      "est_delivery_days": 3,
185      "shipment_id": "shp_ca70827221b04ad589f0d170ec933f52",
186      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
187    },
188    {
189      "id": "rate_c1a6b070dd9d45acb3f3a3eaf3a439bd",
190      "object": "Rate",
191      "created_at": "2024-01-24T00:05:54Z",
192      "updated_at": "2024-01-24T00:05:54Z",
193      "mode": "test",
194      "service": "ParcelSelect",
195      "carrier": "USPS",
196      "rate": "6.79",
197      "currency": "USD",
198      "retail_rate": "13.15",
199      "retail_currency": "USD",
200      "list_rate": "9.41",
201      "list_currency": "USD",
202      "billing_type": "easypost",
203      "delivery_days": 3,
204      "delivery_date": null,
205      "delivery_date_guaranteed": false,
206      "est_delivery_days": 3,
207      "shipment_id": "shp_ca70827221b04ad589f0d170ec933f52",
208      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
209    }
210  ],
211  "refund_status": null,
212  "scan_form": null,
213  "selected_rate": null,
214  "tracker": null,
215  "to_address": {
216    "id": "adr_5795ce04ba4c11ee8d39ac1f6bc539ae",
217    "object": "Address",
218    "created_at": "2024-01-24T00:05:54+00:00",
219    "updated_at": "2024-01-24T00:05:54+00:00",
220    "name": "Dr. Steve Brule",
221    "company": null,
222    "street1": "179 N Harbor Dr",
223    "street2": null,
224    "city": "Redondo Beach",
225    "state": "CA",
226    "zip": "90277",
227    "country": "US",
228    "phone": "8573875756",
229    "email": "dr_steve_brule@gmail.com",
230    "mode": "test",
231    "carrier_facility": null,
232    "residential": null,
233    "federal_tax_id": null,
234    "state_tax_id": null,
235    "verifications": {}
236  },
237  "usps_zone": 4,
238  "return_address": {
239    "id": "adr_57988df8ba4c11ee8d3bac1f6bc539ae",
240    "object": "Address",
241    "created_at": "2024-01-24T00:05:54+00:00",
242    "updated_at": "2024-01-24T00:05:54+00:00",
243    "name": "EasyPost",
244    "company": null,
245    "street1": "417 Montgomery Street",
246    "street2": "5th Floor",
247    "city": "San Francisco",
248    "state": "CA",
249    "zip": "94104",
250    "country": "US",
251    "phone": "4153334445",
252    "email": "support@easypost.com",
253    "mode": "test",
254    "carrier_facility": null,
255    "residential": null,
256    "federal_tax_id": null,
257    "state_tax_id": null,
258    "verifications": {}
259  },
260  "buyer_address": {
261    "id": "adr_5795ce04ba4c11ee8d39ac1f6bc539ae",
262    "object": "Address",
263    "created_at": "2024-01-24T00:05:54+00:00",
264    "updated_at": "2024-01-24T00:05:54+00:00",
265    "name": "Dr. Steve Brule",
266    "company": null,
267    "street1": "179 N Harbor Dr",
268    "street2": null,
269    "city": "Redondo Beach",
270    "state": "CA",
271    "zip": "90277",
272    "country": "US",
273    "phone": "8573875756",
274    "email": "dr_steve_brule@gmail.com",
275    "mode": "test",
276    "carrier_facility": null,
277    "residential": null,
278    "federal_tax_id": null,
279    "state_tax_id": null,
280    "verifications": {}
281  },
282  "forms": [],
283  "fees": [],
284  "id": "shp_ca70827221b04ad589f0d170ec933f52",
285  "object": "Shipment"
286}