CSV Import lets you add tracking numbers to multiple WooCommerce orders at once by uploading a formatted .csv file. It is ideal when fulfilling bulk orders or when your shipping carrier portal or software exports tracking data as a CSV.
To automate CSV imports on a schedule without manual uploads, see Automated CSV Import (FTP/SFTP).
File requirements
- Format:
.csv(comma-separated values), UTF-8 encoding - Header row required — the first row must contain the column names exactly as shown in the field table below
- Column order does not matter — the importer maps by header name
- Extra columns are ignored
- Date format must match the Shipped Date format selected during upload —
DD-MM-YYYYorMM-DD-YYYY - No enforced row limit, but very large files take longer — leave the browser tab open until the import completes
Import steps
- 1Go to WooCommerce → Shipment Tracking → CSV Import.
- 2Click Choose file and select your
.csvfile. - 3Select the Shipped Date format that matches the dates in your file (
DD-MM-YYYYorMM-DD-YYYY). - 4Check Replace tracking information if you want to overwrite existing tracking entries for matching orders. When checked, all previous tracking on a matched order is replaced. When unchecked, new tracking is added alongside existing entries.
- 5Click Upload file and import. A live progress log shows each row as it is processed — success rows show the order ID and confirmation; failed rows show the error reason.
- 6When complete, a summary shows the count of successful and failed rows.
CSV field reference
| Field | Required | Description |
|---|---|---|
order_id | Yes | WooCommerce order ID (numeric). If you use sequential order number plugins, use the internal WooCommerce ID, not the display number. With HPOS this is the order ID. |
tracking_provider | Yes | Carrier name — must match an enabled carrier name or a configured API alias exactly (case-sensitive). |
tracking_number | Yes | The tracking number for the shipment. |
date_shipped | Yes | Shipment date in DD-MM-YYYY or MM-DD-YYYY format — must match the format selected during upload. |
status_shipped | Yes | 0 = no status change; 1 = mark as Shipped; 2 = mark as Partially Shipped. |
shipping_note | No | Customer-visible note shown alongside tracking details. |
sku | No | Product SKU for per-item (Tracking Per Item) tracking. |
qty | No | Quantity of the SKU in this shipment (used with sku). |
Standard CSV format
| order_id | tracking_provider | tracking_number | date_shipped | status_shipped | shipping_note |
|---|---|---|---|---|---|
| 101 | UPS | 1Z6E36W60390858267 | 12-06-2025 | 1 | Shipped via express |
| 102 | USPS | 9200190244541430003 | 12-06-2025 | 1 | Final shipment |
Tracking Per Item CSV formats
Use these formats when assigning tracking to specific items within an order.
Format 1 — one row per tracking number, multiple SKUs comma-separated: use when all the items in the first package share the same tracking number.
| order_id | tracking_provider | tracking_number | date_shipped | status_shipped | sku | qty | shipping_note |
|---|---|---|---|---|---|---|---|
| 119 | USPS | 9200190244541430003 | 12-06-2025 | 2 | t-shirt,blue-jeans | 1,1 | Partial shipment |
| 119 | USPS | 9200190244541445651 | 13-06-2025 | 1 | t-shirt,blue-jeans | 1,1 | Final shipment |
Format 2 — one row per SKU per tracking number: use when different quantities of different SKUs share the same tracking number and you want a separate row per item line.
| order_id | tracking_provider | tracking_number | date_shipped | status_shipped | sku | qty | shipping_note |
|---|---|---|---|---|---|---|---|
| 119 | USPS | 9200190244541430003 | 12-06-2025 | 2 | t-shirt | 1 | Partial shipment |
| 119 | USPS | 9200190244541430003 | 12-06-2025 | 2 | blue-jeans | 1 | Partial shipment |
| 119 | USPS | 9200190244541445651 | 13-06-2025 | 1 | t-shirt | 1 | Final shipment |
| 119 | USPS | 9200190244541445651 | 13-06-2025 | 1 | blue-jeans | 1 | Final shipment |
Viewing the import log
If you need to review errors after the import screen is closed, go to WooCommerce → Status → Logs and filter by source ast-pro-csv-import.
Troubleshooting
- Rows failing with carrier not found — the carrier name must match exactly (case-sensitive). Copy the name from Shipping Carriers or set up an API alias.
- Dates failing — confirm the date format in your file matches the format selected on the upload screen. The importer does not auto-detect date format.
- Order not found errors — use the internal WooCommerce order ID. If you use a sequential order number plugin, the display number may differ from the ID.
- Import stops mid-way — the import runs in your browser. Navigating away or a PHP timeout will interrupt it. For large files, use Automated FTP/SFTP Import instead.