Bulk shipping labels from a CSV

What a shipping CSV actually has to contain

Less than most people assume, and in a stricter form than most people expect. Eight fields have to resolve before a row can be bought: recipient name, address line 1, city, a two-letter ISO country code, weight, length, width, and height. That is the whole required set. Everything else in the catalog is optional — order number, company, email, phone, address line 2, state or province, postal code, package type, a pinned carrier, a pinned service, and the three customs columns of declared value, item description, and HS code.

Two of those deserve calling out because they are where clean-looking files break. Country has to be ISO-2 — US, GB, HK — not "United States" and not "USA", because that code is what selects which carrier services are even eligible for the row. And the three dimensions are required, not the nice-to-have they are on a single manual shipment, because a file is quoted without a human looking at each box. The one exception is a USPS flat-rate container: map the package type column instead and the dimensions stop mattering, since the container defines them.

Your file almost certainly does not use those names, and it does not have to. Headers are matched after lower-casing and stripping punctuation, so "Ship To Postal Code", "shipping_zip" and "Zip Code" all land on the same field, and the usual Shopify, Etsy, Amazon and eBay export headers are recognised on sight. One deliberate exception: any column starting with "From" is never auto-mapped, because bulk import always ships from your account's saved sender address and marketplace exports habitually put junk in their From columns.

Mapping columns once and saving it: the second file takes minutes

Auto-detection gets most of the way and then stops, because no heuristic knows whether your "Total" column is the order total or the declared customs value. The mapping step is one dropdown per field, grouped by recipient, address, package, customs, and service, with the required ones marked — you finish what auto-detection started, set whether weights are pounds or kilos and dimensions inches or centimetres, and you are done.

Then save it under a name. "Etsy export", "backer survey", "wholesale PO". The next file of the same shape applies that preset in one click, and the presets list is yours to manage — apply, rename by saving again, delete. This is the difference between a one-off import and a repeatable process: the first file costs you ten minutes of mapping, and every file after it costs you the upload. If you are fulfilling a crowdfunding campaign, the late-pledge file and the replacement-parts file are the same shape as the original survey export, which is exactly the case presets are for — shipping labels for Kickstarter covers the rest of that job. Wholesale sellers get the same benefit from the opposite direction: a Faire purchase order has the same columns every month, and shipping labels for Faire explains why each carton in a multi-carton order needs its own row.

Validating before you pay, not after the boxes come back

The validate step is the reason to do this in a wizard rather than a script that buys as it reads. Every row is checked before any money moves: required fields present, address accepted by the carrier network, country code valid, weights and dimensions in range, phone and email well-formed where they are supplied, and a restricted-goods keyword scan that mirrors the one a single shipment gets — so a row that would be refused at purchase is refused now, at the point where fixing it is free.

Rows come back with their problems named on the row rather than as a count at the top. A missing secondary unit, a postal code that does not match the city, an ISO code that is actually a country name — you edit, re-check, and move on. Good rows do not wait for bad ones; they proceed to quoting while you repair the rest. This is the single highest-value step in the whole flow, because the alternative version of catching these is a pallet of returns three weeks later, and what happens to a parcel that comes back costs the label twice plus the packaging.

Once rows are valid they are quoted in batch against USPS, UPS, FedEx, and DHL, and each row takes the cheapest all-in option for its own parcel — not one carrier chosen for the whole file. Rows that have to go a specific way keep their pinned carrier or service from the mapped columns. International rows use the customs columns you mapped; duties default to the recipient unless you explicitly choose to prepay them, and what to write on the form is on customs forms for small parcels.

What happens when a row fails mid-file

Purchasing runs sequentially, one row at a time, and that is a deliberate design decision rather than a performance limitation. A parallel fan-out would let two rows clear the same wallet-balance check against the same starting balance and over-debit you; serialising the purchases makes the balance arithmetic exact. It also means a failure is contained to its own row instead of poisoning the batch.

So when a row fails — the carrier declines it, the address turns out to be undeliverable at purchase time, the balance will not stretch — that row reports its own error and the file carries on or stops with the reason visible. You get a summary of how many purchased, how many were skipped, and how many failed, and you can retry a single failed row without touching the ones that worked. Re-running a file you have already partly bought is safe: rows with a label already attached are recognised and skipped rather than purchased a second time.

One thing to know before a very large run: on the Free plan the monthly shipment allowance is enforced per row as the batch executes, so a file that starts under the cap stops exactly at it rather than silently overshooting, and the remaining rows report why. A single file is capped at 500 rows, so larger exports get split — which is a reasonable review checkpoint anyway. The plan detail is on pricing.