Bulk CSV Format Guide
Everything you need to prepare a CSV file for the bulk shipping uploader. Download a template, fill it in, and ship hundreds of packages in one transaction.
Quick start
- Download one of the templates above.
- Open it in Excel, Google Sheets, or any spreadsheet app.
- Add one shipment per row. Leave optional columns blank — do not delete them.
- Export or save as CSV (UTF-8 encoding).
- Upload on the Bulk Upload page.
Column Reference
Column order does not matter — the header row is used to match columns. Names are case-insensitive.
| Column | Required | Type | Description | Example |
|---|---|---|---|---|
| sender_name | required | text | Full name of the sender | John Smith |
| sender_company | optional | text | Company name (optional) | Acme Corp |
| sender_address1 | required | text | Street address line 1 | 123 Main St |
| sender_address2 | optional | text | Apartment, suite, unit (optional) | Apt 4B |
| sender_city | required | text | City | New York |
| sender_state | required | 2-char | State abbreviation (2 letters) | NY |
| sender_zip | required | text | ZIP or postal code | 10001 |
| sender_country | optional | 2-char | ISO 3166-1 alpha-2 country code — defaults to US | US |
| recipient_name | required | text | Full name of the recipient | Jane Doe |
| recipient_company | optional | text | Company name (optional) | |
| recipient_address1 | required | text | Street address line 1 | 456 Oak Ave |
| recipient_address2 | optional | text | Unit or floor (optional) | |
| recipient_city | required | text | City | Los Angeles |
| recipient_state | required | 2-char | State abbreviation (domestic) or province code | CA |
| recipient_zip | required | text | ZIP or postal code | 90001 |
| recipient_country | optional | 2-char | ISO 3166-1 alpha-2 country code — defaults to US | US |
| weight_lbs | optional | decimal | Weight in pounds — added to weight_oz. Use either or both. | 1 |
| weight_oz | optional | decimal | Weight in ounces — added to weight_lbs. At least one must be > 0. | 8 |
| length_in | optional | decimal | Length in inches. Required when package_type is "custom". | 10 |
| width_in | optional | decimal | Width in inches. Required when package_type is "custom". | 8 |
| height_in | optional | decimal | Height in inches. Required when package_type is "custom". | 4 |
| package_type | optional | text | Predefined package code or "custom" (default). See package types below. | SmallFlatRateBox |
| carrier | optional | text | Carrier code to restrict rate selection. See carrier codes below. | USPS |
| service | optional | text | Service name keyword for rate selection (combined with carrier). | PRIORITY |
| optional | Recipient email for per-shipment tracking notification. | jane@example.com |
Weight
weight_lbs and weight_oz are added together. A 1 lb 8 oz package can be expressed as:
weight_lbs=1, weight_oz=8→ 24 ozweight_lbs=0, weight_oz=24→ 24 ozweight_lbs=1.5, weight_oz=0→ 24 oz
Maximum total weight: 70 lbs.
Package Types
When using a predefined package, dimensions are ignored — only weight is used. Flat-rate pricing is fixed by the carrier, but weight is still required (the carrier needs it for eligibility checks). Use weight_lbs or weight_oz.
| package_type value | Carrier | Description |
|---|---|---|
| custom | Any | Custom dimensions (length × width × height + weight). Default when left blank. |
| FlatRateEnvelope | USPS | Standard Flat Rate Envelope |
| FlatRateLegalEnvelope | USPS | Legal-size Flat Rate Envelope |
| FlatRatePaddedEnvelope | USPS | Padded Flat Rate Envelope |
| SmallFlatRateBox | USPS | Small Flat Rate Box |
| MediumFlatRateBox | USPS | Medium Flat Rate Box |
| LargeFlatRateBox | USPS | Large Flat Rate Box |
| Parcel | USPS | Parcel (irregular dimensions allowed) |
| SoftPack | USPS | Soft-pack / padded mailer |
| Flat | USPS | Large envelope / flat |
| Letter | USPS | Standard letter |
Any unrecognised value falls back to custom — dimensions will be used.
Carrier & Service Selection
By default the system picks the cheapest available rate. Use the carrier and service columns to pin a row to a specific carrier or service.
Selection priority (per row)
- 1
carrier+servicecolumns — most precise - 2Global mode (cheapest / fastest) set on the upload page
| carrier value | Carrier name | Example service values |
|---|---|---|
| USPS | United States Postal Service | FIRST_CLASS, PRIORITY, EXPRESS, PARCEL_SELECT |
| UPS | UPS | GROUND, 3_DAY_SELECT, 2ND_DAY_AIR, NEXT_DAY_AIR |
| FEDEX | FedEx | GROUND, HOME_DELIVERY, 2_DAY, PRIORITY_OVERNIGHT |
| DHL | DHL Express | EXPRESS_WORLDWIDE, PAKET, GLOBALMAIL_BUSINESS |
Service matching is a substring search — PRIORITY matches both PRIORITY_MAIL and PRIORITY_MAIL_EXPRESS. If no match is found for a row, the global cheapest/fastest mode is used as a fallback.
Example CSV
Three rows showing cheapest-rate, flat-rate box, and carrier-pinned with email notification.
sender_name,...,weight_lbs,weight_oz,length_in,width_in,height_in,package_type,carrier,service,email John Smith,...,0,8,10,8,4,custom,USPS,, John Smith,...,0,0,0,0,0,SmallFlatRateBox,USPS,, John Smith,...,1,0,12,10,6,custom,FEDEX,GROUND,alice@example.com
Download the full template above for all columns with real example data.
International Shipments
Set recipient_country to any valid ISO 3166-1 alpha-2 code (e.g. GB, CA, AU).
Postal codes and state/province formats vary by country — use whatever the destination country's postal service requires.
Some carriers charge dimensional weight for large, light packages. Provide accurate dimensions even if they are larger than expected.