Bulk upload orders

Download the CSV template directly from the upload page in Dashboard. The template includes all required and optional columns — required columns are marked with an asterisk (*) in the header row.

One row per item 

Each row represents one item, not one order. Rows that share the same Order ID are grouped into a single multi-item order, so a three-item order is three rows. Order-level values — recipient, address, service level, shipping amount, currency, duty paid by, and carton — are read from the first row of each group.

Required columns 

The required information for each row falls into three categories:

Recipient — The name, phone number, and shipping address of the recipient, including destination country. Email is optional, but it is validated for format when you provide one. Postal code and state/province are required only for countries whose address format uses them — for a country without postal codes (e.g., Hong Kong or Tanzania), simply leave the cell blank. For countries with a state/province list, use a recognized region name or code (e.g., "Dubayy" or "DU" for Dubai) so carriers can rate the destination.

Items — At minimum, item name and price. Quantity is optional and defaults to 1. Providing an HS code and country of origin improves classification accuracy and can reduce processing time on the confirmation screen.

Shipping — A service level code that matches a carrier configured on your account (e.g., fedex.international_priority, ups_worldwide_expedited). The Shipping Amount column is optional: enter an amount (0 is allowed) to use it as the order's shipping charge, or leave it blank and a carrier-rate estimate is calculated for your service level. Calculated rows take a few extra seconds each on the confirmation screen, and the final carrier charge at label creation can differ from the estimate. Some destinations can't be rated automatically (a "service not available for destination country" error) — enter a shipping amount on just those rows; blank and filled rows can mix freely in one file.

Optional columns 

Recipient tax ID — Use the Tax ID Type and Tax ID Number columns to include a recipient tax identifier on the order. The type must be one of the codes below (case-insensitive). Provide both columns together; a type without a number (or vice versa) is flagged as an error on the confirmation screen. The tax ID is saved on the order's recipient and passed to the carrier when a label is created. For multi-item orders, the tax ID from the order's first row is used.

Use the country-specific code where one exists; for any country not listed, use TIN.

Additional special-purpose codes (FED, FTZ, DUN, and the DAN/TAN/DTF duty and tax deferment accounts) are accepted when your Zonos representative directs you to use one.

Duty Paid By — Optional DDP or DDU per order. Leave it blank for the default behavior: DDP wherever the destination supports it, with automatic fallback to DDU where it doesn't. An explicit DDP is strict — rows error instead of falling back — and DDU makes the recipient responsible for duties and taxes on delivery. The confirmation screen and results download show which one each order actually landed on, with an orange badge on DDU rows. For multi-item orders the first specified value wins, and conflicting values are an error.

Carton quantity — If an order ships in multiple identical boxes, set Carton Quantity alongside the Carton Length/Width/Height/Weight columns. The carton columns describe one box (the weight is the weight of a single packed box), and the quantity multiplies it — for example, 360 units packed 30 to a box would use the box dimensions, the weight of one full box, and a carton quantity of 12. Blank means 1. Orders with mixed box sizes can't be described in the CSV — leave the carton columns blank on those orders and Zonos will box them automatically based on item weights.

Tips 

• Use the exact service level codes shown in your carrier settings. Rows with unrecognized service level codes will show a warning on the confirmation screen.
• US territories differ: the US Virgin Islands use their own country code (VI) and ship as international, while Puerto Rico uses US and ships as domestic.
• Carriers (UPS in particular) refuse P.O. Box delivery addresses — rows with "P.O. Box" in an address line can fail rating with a generic service-availability error. Use a street address where possible.
• Typographic punctuation from Word or Excel (curly quotes, en/em dashes) is corrected automatically. Question marks appearing where accented letters should be indicate the file lost its encoding — those rows are flagged so you can re-enter the text.
• For destination countries that require a state or province code (e.g., Brazil, US, Canada), ensure the state field is populated with the correct ISO code.
• The Order ID is required and must be unique across your account, including previous uploads — an ID that was ever used before (even in an earlier season's file or a cancelled order) is rejected at order creation. Reusing a file? Add a suffix to the IDs (for example ACALB-33 for volume 33). The ID appears on the confirmation screen and carries through to the created order as the merchant reference.
• Recipient names, addresses, city, state/province, company name, and item names must use Latin characters. Non-Latin scripts such as Japanese or Arabic are rejected.
• Fully blank rows are ignored, so trailing empty rows in your file are harmless.

Every column in the standard template, in template order. Conditional means the column is only required in certain cases — see Required columns above for the details.

Japan Post uses its own CSV template, downloaded from the upload page the same way. It has no service level column — the upload assigns the carrier's first service level and you re-select one in the label flow — and no carton quantity column, since these uploads always ship as a single carton.

Columns that are optional on the standard template but required for Japan Post:

• HS code
• Country of origin
• Item weight — the weight unit stays optional here and defaults to grams
• Postal code
• State/province
• Shipping amount — unlike the standard template, this cannot be left blank

The template also adds Japan Post shipping fields that are stored on the order and applied to the shipment when a label is created: Contents Type, Licence Number, Certificate Number, Invoice, Tax Code/VAT Number, Pay Condition, Remarks, Sender's Reference Number, and Non-commercial. All are optional. The text fields accept up to 25 characters, and Non-commercial accepts only true or false.

After uploading, a confirmation screen displays the calculated landed cost breakdown for each order before anything is created. The screen shows:

Rows can show $0 duties, taxes, and fees when the destination doesn't charge import fees at the shipment's declared value (it is under the country's de minimis threshold) — the landed cost is genuinely zero, not missing, and shipping is the only cost for those orders.

The Create orders button displays the count of orders that will be submitted (e.g., Create 17 orders). Only rows with Ready or Warning status are included — rows with errors are excluded.

Use Download results CSV to export the full quote breakdown (selected rate, item total, shipping, duties, taxes, fees, and totals per order) — useful for quoting your customers before any orders are created. Click Start over to discard the upload and start fresh with a revised file.

When you leave Shipping Amount blank, the service level column shows the rate matching your CSV's service level. If your requested service level isn't available for a destination, the closest available rate is selected and flagged with a Different service level badge — or, when several alternatives exist, a Select a rate dropdown lets you choose before the order can be created.

Issues are flagged inline on the confirmation screen.

Errors 

Rows with errors are excluded when you click Create orders. Fix the issue in your CSV and re-upload to include those rows. Common errors include:

• Low-value orders not allowed — The order value is below the minimum threshold for your store.
• Invalid state code — The state or province code is not valid for the destination country. Required for countries like Brazil, the US, and Canada.
• Missing required field — A required column is empty or cannot be parsed.
• Order ID already exists — Each order ID must be unique across your account, including orders from previous uploads. Rows with already-used IDs fail at creation while the rest of the file succeeds — re-upload just the failed rows with fresh IDs (a suffix like -33 works well).

Warnings 

Rows with warnings are included in the submission. Review them before clicking Create orders. Common warnings include:

• Service level not configured — The service level code in your CSV is not connected to your account. The order will be created but may not rate correctly. Verify your carrier settings or update the service level code in your CSV.

The current upload limit is 200 orders per CSV. Orders are submitted in batches of up to 50 per API call — if your upload contains more than 50 ready orders, they are processed in multiple batches automatically.

Coming soon: A future update will remove the 200-order cap and add background job processing for larger uploads.