How to upload orders
- Go to Dashboard -> Orders -> Manage -> Upload orders.
- Download the CSV template from the upload page and populate it with your order data.
- Upload your completed CSV.
- Review the confirmation screen — landed costs are calculated per row and any errors or warnings are shown inline.
- Click Create orders to submit all Ready orders.
CSV format
Download the CSV template directly from the upload page in Dashboard. The template includes all required and optional columns pre-labeled with example values.
Required columns
Each row represents one order. The required information for each row falls into three categories:
Recipient — The name, email, and shipping address of the recipient, including destination country.
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).
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.
- 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_idcolumn is optional but recommended — it appears on the confirmation screen and carries through to the created order as the merchant reference.
Review the confirmation screen
After uploading, a confirmation screen displays the calculated landed cost breakdown for each order before anything is created. The screen shows:
| Column↕ | Description↕ |
|---|---|
| Order ID | The reference ID from your CSV. |
| Items | Item name and quantity. |
| Recipient | The recipient's name. |
| Country | The destination country. |
| Service level | The shipping service level used for rating. |
| Item total | The declared item value. |
| Shipping | The calculated shipping cost. |
| Duties | The calculated duties. |
| Taxes | The calculated taxes. |
| Fees | The Zonos fees. |
| LC total | The total landed cost (duties + taxes + fees). |
| Grand total | The total including item value and landed cost. |
| Status | Ready, Warning, or Error. |
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.
Errors and warnings
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.
Limits and batch processing
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.
Bulk upload orders
Create up to 200 orders at once by uploading a CSV file.Instead of creating orders one at a time, you can upload a CSV file to create orders in bulk directly from Dashboard. This is a good option when you need to process a large number of shipments at once. Landed costs are calculated on the fly for each row and displayed on a confirmation screen before any orders are submitted, so you can review the full cost breakdown across your entire batch before committing.