This article explains how to use EasyPost's CSV integration to bulk-create shipping labels by uploading a CSV with shipment details and receiving a file containing the generated labels.
Getting Started
- Log in to the EasyPost Dashboard.
- Navigate to Shipments within the left menu.
Labels can also be created individually using a simple form, or use the CSV upload feature for batch processing.
Note: Ensure the account is funded (see the Billing section for details) before creating shipping labels.
Step 1: Fill out the CSV template
- Download the CSV template (an International Template is also available ) and input shipment details.
- Delete example rows before saving.
- Save the completed file as a CSV.
Note: Each CSV supports up to 500 shipments; for more, submit additional CSV files.
Valid CSV Headers
to_address.name to_address.company to_address.phone to_address.email to_address.street1 to_address.street2 to_address.city to_address.state to_address.zip to_address.country |
from_address.name from_address.company from_address.phone from_address.email from_address.street1 from_address.street2 from_address.city from_address.state from_address.zip from_address.country |
parcel.height_in
|
carrier
|
Note: Leave parcel.predefined_package blank if not using a predefined package. Valid predefined packages can be found in EasyPost's Predefined Packages documentation.
A carrier and service must be specified for each shipment. Only carriers added to the EasyPost account are available. USPS is included by default, with numerous supported service levels.
International Shipping
For international shipping, the CSV requires additional customs fields. Use the International CSV Template and add the following headers:
Field |
Description |
Example |
---|---|---|
customs.customs_certify | Electronically certify the information provided | TRUE |
customs.customs_signer | Person certifying the information | Sally Smith |
customs.contents_type | "documents", "gift", "merchandise", "returned_goods", "sample", or "other" | merchandise |
customs.restriction_type | "none", "other", "quarantine", or "sanitary_phytosanitary_inspection" | none |
customs.eel_pfc | value less than $2500: "NOEEI 30.37(a)"; value greater than $2500: see Customs Guide | NOEEI 30.37(a) |
customs_item.description | Description of item being shipped | Men's T-Shirt |
customs_item.quantity | Description of item being shipped | 1 |
customs_item.weight_oz | Total weight (unit weight * quantity) in ounces | 32 |
customs_item.value | Total value (unit value * quantity) | 19.99 |
customs_item.code | SKU/UPC or other product identifier | mens-blue-shirt |
customs_item.hs_tariff_number | Harmonized Tariff Schedule, e.g. "6109.10.0012" for Men's T-shirts | 6109.10.0012 |
customs_item.origin_country | Required, 2 char country code | US |
Note: As of December 2020, only one customs item per international shipment is supported in the CSV.
Printing a Custom Message on the Label
To add a custom message, add a column titled options.print_custom_1 in the CSV and enter the desired text. The locations of these fields appear in different places on the carrier's labels.
Additional Shipping Options
View the complete list of supported headers for additional shipping options.
Step 2: Upload the CSV
- Log in to the EasyPost Dashboard.
- Navigate to Shipments within the left menu.
- Select the Buy a label with CSV button.
- Attach the CSV file. Optionally, nickname the upload for easier tracking.
- Select Buy Labels to initiate the label generation process.
Note: Ensure the account is funded (see the Billing section for details) before creating shipping labels.
Step 3: Download and Print Labels
- Upon confirmation, review the total label count and costs per carrier.
- Select the preferred format (PDF, ZPL, EPL2) for printing.
- Click Download labels.
Tip: Use the Shipment area of the dashboard to view information on individual shipments.
Error Handling
If the batch has errors, download a CSV listing the error messages and failed shipments by clicking Download and Remove Errors. Correct the issues in the CSV and re-upload only the failed shipments.
Supported Headers
For additional shipping options, the list below includes advanced options supported through the CSV upload tool.
reference | |||
is_return | |||
from_address.name | to_address.name | return_address.name | buyer_address.name |
from_address.company | to_address.company | return_address.company | buyer_address.company |
from_address.phone | to_address.phone | return_address.phone | buyer_address.phone |
from_address.email | to_address.email | return_address.email | buyer_address.email |
from_address.street1 | to_address.street1 | return_address.street1 | buyer_address.street1 |
from_address.street2 | to_address.street2 | return_address.street2 | buyer_address.street2 |
from_address.city | to_address.city | return_address.city | buyer_address.city |
from_address.state | to_address.state | return_address.state | buyer_address.state |
from_address.zip | to_address.zip | return_address.zip | buyer_address.zip |
from_address.country | to_address.country | return_address.country | buyer_address.country |
from_address.residential | to_address.residential | return_address.residential | buyer_address.residential |
from_address.carrier_facility | to_address.carrier_facility | return_address.carrier_facility |
buyer_address.carrier_facility
|
from_address.federal_tax_id | to_address.federal_tax_id | return_address.federal_tax_id |
buyer_address.federal_tax_id
|
from_address.state_tax_id | to_address.state_tax_id | return_address.state_tax_id |
buyer_address.state_tax_id
|
from_address.verify | to_address.verify | return_address.verify | buyer_address.verify |
from_address.verify_strict | to_address.verify_strict | return_address.verify_strict | buyer_address.verify_strict |
parcel.length_in | |||
parcel.width_in | |||
parcel.height_in | |||
parcel.weight_oz | |||
parcel.predefined_package | |||
carrier | |||
service | |||
options.additional_handling | |||
options.address_validation_level
|
|||
options.alcohol | |||
options.by_drone | |||
options.carbon_neutral | |||
options.cod_amount | |||
options.cod_method | |||
options.currency | |||
options.delivery_confirmation
|
|||
options.dropoff_type | |||
options.dry_ice | |||
options.dry_ice_medical | |||
options.dry_ice_weight | |||
options.endorsement | |||
options.freight_charge | |||
options.handling_instructions | |||
options.hazmat | |||
options.hold_for_pickup | |||
options.incoterm | |||
options.invoice_number | |||
options.label_date | |||
options.label_format | |||
options.machinable | |||
options.bill_third_party_account | |||
options.bill_third_party_country | |||
options.bill_third_party_postal_code | |||
options.print_custom_1 | |||
options.print_custom_2 | |||
options.print_custom_3 | |||
options.print_custom_1_barcode
|
|||
options.print_custom_2_barcode
|
|||
options.print_custom_3_barcode
|
|||
options.print_custom_1_code
|
|||
options.print_custom_2_code
|
|||
options.print_custom_3_code
|
|||
options.saturday_delivery | |||
options.special_rates_eligibility
|
|||
options.smartpost_hub | |||
options.smartpost_manifest | |||
options.billing_ref | |||
options.certified_mail | |||
options.registered_mail | |||
options.registered_mail_amount
|
|||
options.return_receipt | |||
customs.customs_certify | |||
customs.customs_signer | |||
customs.contents_type | |||
customs.restriction_type | |||
customs.eel_pfc | |||
customs_item.description | |||
customs_item.quantity | |||
customs_item.weight_oz | |||
customs_item.value | |||
customs_item.code | |||
customs_item.hs_tariff_number
|
|||
customs_item.origin_country |
Additional Resources
Please contact the EasyPost support team for assistance with CSV uploads and provide the CSV, any error messages, and screenshots.
EasyPost API Docs: Shipment Options