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 the template 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 | Defaults to US. Bulk upload supports US-to-US shipments only. | 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 | Defaults to US. Bulk upload supports US-to-US shipments only. | 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 |
| UPSLetter | UPS | UPS Express Envelope (incl. legal size), up to 1 lb |
| SmallExpressBox | UPS | UPS Express Box — Small |
| MediumExpressBox | UPS | UPS Express Box — Medium |
| LargeExpressBox | UPS | UPS Express Box — Large |
| UPSPak | UPS | UPS Pak — flexible padded envelope |
| UPSTube | UPS | UPS Tube — for rolled papers |
| FedExEnvelope | FEDEX | FedEx Envelope, up to 10 lbs |
| FedExPak | FEDEX | FedEx Pak, up to 20 lbs |
| FedExTube | FEDEX | FedEx Tube |
| FedExSmallBox | FEDEX | FedEx Small Box |
| FedExMediumBox | FEDEX | FedEx Medium Box |
| FedExLargeBox | FEDEX | FedEx Large Box |
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 | Notes |
|---|---|---|---|
| USPS | United States Postal Service | FIRST, PRIORITY, EXPRESS, GROUND_ADVANTAGE, PARCEL_SELECT | — |
| UPS | UPS | GROUND, 3_DAY_SELECT, 2ND_DAY_AIR, NEXT_DAY_AIR | Requires a funded Adjustment Reserve |
| FEDEX | FedEx | GROUND, HOME_DELIVERY, 2_DAY, PRIORITY_OVERNIGHT | Requires a funded Adjustment Reserve |
Service matching ignores case, underscores, and spaces — 2ND_DAY_AIR, 2nd day air, and 2ndDayAir are equivalent, and PRIORITY matches every Priority-family service. If no service matches for a row, the global cheapest/fastest mode is used as a fallback.
UPS & FedEx require an Adjustment Reserve
Rows pinned to UPS or FEDEX are only available to logged-in, email-verified accounts with a funded Adjustment Reserve. Uploads containing UPS/FedEx rows without a funded reserve are rejected before payment. USPS rows have no such requirement.
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
Bulk upload is US-to-US only. International shipments require a customs declaration (contents, values, HS codes), which the CSV format does not carry. Rows with a non-US recipient_country are rejected during validation.
To ship internationally, use the single-label flow, which collects the full customs declaration. International-only carriers such as DHL Express become available there once the destination country is set to a non-US address.