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.

Required columns 

Each row represents one order. The required information for each row falls into three categories:

Recipient — The name, email, phone number, and shipping address of the recipient, including destination country. 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), leave the cell blank and a carrier-accepted placeholder is filled in automatically.

Items — At minimum, item name, quantity, and price. 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).

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.

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.
• 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 column is optional but recommended — it appears on the confirmation screen and carries through to the created order as the merchant reference.

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

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.

Click Start over to discard the upload and start fresh with a revised file.

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.

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.