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 |
Mailing from a different location? The sender columns are your return address, printed on each label. If the batch will physically be dropped off somewhere else, set the optional Mailing Origin ZIP on the bulk upload page (not in the CSV) — only the drop-off ZIP Code is needed, and postage for every row is calculated from it while the return address stays on the label. Leave it blank to rate each row from its own sender_zip.
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 |
| SmallFlatRateEnvelope | USPS | Small Flat Rate Envelope (10 × 6 in) |
| 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.