CSV Import Guide & Template
This page documents the same column names and rules as the live batch CSV uploader: one row per shipment, UTF-8 encoding, and validation for addresses, weight, carrier, and (when countries differ) customs.
How CSV upload works
You upload a spreadsheet with a header row; each data row becomes one label quote. After processing you pick rates and pay on the batch checkout page. Automatic volume discounts apply by label count (see tiers below). Friendly column aliases (e.g. “Street Address”) are mapped where supported, but the canonical names below always work.
Minimum required columns
Every row must include these headers exactly as written:
from_name,from_street1,from_city,from_state,from_zip,from_country,to_name,to_street1,to_city,to_state,to_zip,to_country,parcel_weight,carrier
For custom packages (default when package_type is empty or custom), you must also supply
parcel_length, parcel_width, and parcel_height using parcel_distance_unit (default in).
Some predefined package_type values allow omitting dimensions when the carrier supports them.
Full sample header (domestic + optional fields)
Use this single header line if you want optional phones, emails, units, service level, and insurance columns in one file:
from_name,from_street1,from_street2,from_city,from_state,from_zip,from_country,from_phone,from_email,to_name,to_street1,to_street2,to_city,to_state,to_zip,to_country,to_phone,to_email,parcel_length,parcel_width,parcel_height,parcel_weight,parcel_distance_unit,parcel_mass_unit,carrier,service_level,rate_priority,payment_method,stripe_token,email,wallet_address,insurance_amount,insurance_currency
Sender and recipient columns
| Column | Description | Required |
|---|---|---|
from_name | Sender name or business | Yes |
from_street1 | Sender street line 1 | Yes |
from_street2 | Sender apt / suite | No |
from_city, from_state, from_zip | Sender city, region code, postal code | Yes |
from_country | ISO 2-letter country (e.g. US, CA) | Yes |
from_phone, from_email | Sender contact (recommended for some carriers) | No |
to_name | Recipient name | Yes |
to_street1 | Recipient street line 1 | Yes |
to_street2 | Recipient apt / suite | No |
to_city, to_state, to_zip | Recipient city, region code, postal code | Yes |
to_country | ISO 2-letter country | Yes |
to_phone, to_email | Recipient contact | No |
Parcel, carrier, and rate selection
| Column | Description | Required |
|---|---|---|
parcel_weight | Total shipment weight; unit from parcel_mass_unit (default lb) | Yes |
parcel_mass_unit | e.g. lb, kg, oz | No |
parcel_length, parcel_width, parcel_height | Dimensions in parcel_distance_unit (default in); required for custom packages | Conditional |
parcel_distance_unit | in or cm | No |
package_type | custom or a carrier-specific predefined package | No |
carrier | Carrier token (e.g. usps, ups, fedex, canadapost) | Yes |
service_level | Optional specific service code | No |
rate_priority | best_value (default), cheapest, or fastest | No |
signature_confirmation | Carrier signature option when supported | No |
email | Order / delivery email | No |
payment_method, stripe_token, wallet_address | Advanced: most users pay on the batch checkout screen after upload | No |
insurance_amount, insurance_currency | Optional declared value | No |
International rows (different from_country and to_country)
When sender and recipient countries differ, customs data is required. Use the International CSV template below for a full header including customs columns.
You can supply either a single line item via customs_description and related fields, or multiple items in customs_items as JSON (see the batch import page for examples).
| Column | Description | Typical |
|---|---|---|
customs_contents_type | e.g. MERCHANDISE, GIFT, DOCUMENTS | Required |
customs_contents_explanation | Short summary of contents | Required |
customs_non_delivery_option | RETURN or ABANDON | Required |
customs_certify_signer | Signer name (defaults to sender if omitted) | Often required |
customs_description | Single-item description (truncated per carrier rules) | Or use JSON |
customs_quantity, customs_value_amount, customs_net_weight | Qty, declared value, item weight | With simple line |
customs_origin_country, customs_mass_unit, customs_value_currency | Origin ISO code, weight unit, currency | With simple line |
customs_items | JSON array for multiple customs lines | Alternative |
customs_incoterm, customs_eel_pfc | Trade and compliance fields when needed | Optional |
Total customs item weight must not exceed parcel_weight (after unit conversion) or the row will fail validation.
Bulk Discount Tiers (Applied Automatically)
We reward volume! When you upload a CSV file with multiple labels, your total cost will receive an automatic discount based on how many valid labels are in your file:
| Label Count | Discount |
|---|---|
| 10+ | 5% off |
| 25+ | 8% off |
| 50+ | 10% off |
| 75+ | 12% off |
| 100+ | 15% off |
Discounts are applied before checkout and reflected in your order summary.
Important notes
- Save as UTF-8 CSV; a single header row; no blank required cells.
- Weights use
parcel_weight+parcel_mass_unit(default pounds). Dimensions useparcel_length/parcel_width/parcel_height+parcel_distance_unit(default inches). - Leave optional fields like
from_street2orto_street2empty when not used—do not delete the column if your template includes it. - Use ASCII-friendly address text when possible to avoid carrier address-parser issues.
Download CSV Template
Download CSV template International CSV template
Once Uploaded
- Your file will be processed securely
- Labels will be generated and delivered to your email
- Any file errors will be flagged automatically
Need Help?
If you’re unsure how to format your file, contact support — we’re happy to help!