Bulk shipping labels from a CSV

What columns does a shipping CSV need?

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 "Shipping 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. If the reason you are exporting at all is that Shopify has paused label buying, skip the file: shipping Shopify orders while label buying is on hold covers syncing the store instead.

Download the CSV template

If you are building the file by hand rather than exporting it, start from the template. Its 21 headers are spellings the importer recognises on sight, so every column auto-maps on the mapping step with nothing left to pick, and the three example rows cover the three shapes a file usually mixes: a domestic parcel with dimensions, a USPS flat-rate box with no dimensions, and an international row with the customs columns filled. Delete the examples, keep the header row, add your shipments.

Download goatlabels-bulk-labels-template.csv 21 columns, 3 example rows, 1 KB. Weight in pounds, dimensions in inches.

The dashboard's Upload step also offers Domestic, International and Multi-box template buttons, so you never have to come back here for a copy.

Column mapping: every field, every accepted header

This is the complete field catalog the mapping step offers, with the header spellings auto-detect recognises for each. Matching ignores case, spaces and punctuation, so "Shipping Postal Code", "shipping_postal_code" and "SHIPPINGPOSTALCODE" are the same header. Any header that starts with "From" is skipped on purpose; the file never sets the sender.

* Email and phone are optional columns, but the carrier contact rules checked at the validate step want a recipient phone and email on most rows (USPS and every international service), so a file without them fails validation with "Recipient phone required" rather than at purchase. Weight and dimensions are read in the unit you set on the mapping step, kg or lb and cm or in; a header ending in "(lbs)" switches the weight unit to pounds for you. Boxes is read where multi-box shipments are enabled on your account; elsewhere the row asks you to split it into one row per box.

How to import the file, step by step

The Bulk import page is a four-step wizard and the step names below are the ones on screen. The whole first pass, including saving the preset, takes about fifteen minutes; every file of the same shape after it takes the upload.

1. Upload. In the dashboard open Shipments and choose Bulk import. On the Upload CSV card drop your file on "Drop your CSV here" or click Choose file. The first row must be your column headers; the file must be .csv, UTF-8, under 2 MiB and at most 500 rows. If you do not have an export yet, start from the template above.
2. Map columns. On Map your columns, each GoatLabels field shows the header the auto-detect picked; fix the blanks with one dropdown per field. Set the weight unit (kg or lb) and the dimension unit (cm or in) for the whole file, and optionally a default country, weight or box size for rows that leave the cell empty. Type a name such as "Etsy export" and click Save preset so the next file of the same shape is one click. Then click Validate rows.
3. Validate & quote. Validation results lists every row with its problems named on the row: a missing required field, a country that is not ISO-2, a phone or email the carrier will reject, an undeliverable address. Fix the file or go Back to mapping, re-run, then click Get rates to quote every valid row: USPS, UPS and FedEx on domestic rows, DHL joining on international rows. Each row takes the cheapest all-in option for its own parcel unless its Carrier and Service columns pin it.
4. Purchase. Click Buy labels. Rows are bought one at a time from your prepaid wallet; the summary counts purchased, skipped and failed rows, and a failed row has its own Retry. Re-running a file never buys a row that already has a label. Print the stack from Shipments.

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. A Big Cartel shop has no connector at all, so its order export is the integration, and batch-shipping a Big Cartel drop is one saved preset plus one upload.

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. Most of those defects repeat from file to file, and why a real address fails validation covers each one and its fix.

Once rows are valid they are quoted in batch against USPS, UPS and FedEx, with DHL on international rows, 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.

How a whole shipping day is sequenced around the file, from merging channels to packing against the printed stack, is on the batch fulfillment day workflow. Files exported from a warehouse system follow the same path; the warehouse angle is on shipping labels for warehouses. Print-on-demand shops that ship the stickers, prints, and bundles their provider does not handle use the same file path, and self-fulfilled print-on-demand orders covers which orders to keep in-house.