Bulk CSV upload

Bulk CSV upload

Bulk CSV upload processes hundreds or thousands of shipments through the same calculator engine in a single run. Upload a CSV that matches our column shape, watch the progress bar, and download the results with duty, tax, and fee breakouts per row.

Bulk upload is gated to Pro tier and above. Free tier users see an upgrade prompt when they open the upload page.

How to run a bulk upload

1. Open the bulk upload page from inside the calculator.
2. Download the CSV template. It shows the required columns and one example row.
3. Fill your data into the template. One row per shipment.
4. Save the CSV as UTF-8. Do not use ISO-8859-1 or a Windows codepage; special characters will corrupt.
5. Drop the CSV into the upload zone. The parser validates every row before starting.
6. Click Start. Progress is shown live. Rows that error out are reported with row number and reason.
7. When the job completes, download the results CSV. Every input row is paired with a full CostLayer breakdown.

Jobs run synchronously up to about 500 rows and asynchronously for larger batches. Async jobs email you when they complete.

Required columns

origin_country, destination_country, hs_code, commercial_value, currency, quantity, unit. Optional: freight, insurance, incoterm, client_reference. Use client_reference to tie a result back to your own PO number or invoice ID.

Rows missing any required column fail with a clear error. Missing optional columns fall back to sensible defaults (zero freight, CIF Incoterm, and so on).

Tier limits

Pro is capped at 200 audited line items per month. Growth raises to 2,000 lines per month. Business raises to 10,000 lines per month. Bulk calculator runs count against the same monthly line-item budget as audit runs.

Frequently asked questions

What is the row limit per file

Fifty thousand per file. For larger runs, split the CSV or use the /v1/calc/bulk API endpoint with async mode.

What if a row has an invalid HS code

The row errors out in validation. The rest of the file still runs. You get an errors CSV alongside the results CSV.

Can I re-run a failed row after fixing the HS code

Yes. Fix the error, drop the corrected CSV back into the upload zone, and re-run. Only the failed rows need to be resubmitted.

Is there an API for this

Yes. POST /v1/calc/bulk accepts a JSON array in place of a CSV. See /developers for the schema. Growth tier gates API access.