Bulk upload¶

Import hundreds or thousands of records at once from a CSV file, instead of typing them in one at a time. Bulk upload handles four entity types: LPNs, locations, products, and receiving orders.

When to use bulk upload¶

Accessing bulk upload¶

1. Select Administration in the left sidebar.
2. Select Bulk Upload from the submenu.

The bulk upload interface opens, showing entity type selection, your upload history (if you have any), and a job status tracking panel.

Supported entity types¶

Bulk upload supports four entity types. These are the complete set — the Data Type dropdown in the upload modal offers exactly these four, in this order, and defaults to LPNs:

There is no bulk upload for customers, inventory adjustments, or serial numbers. Serial numbers are imported as a column on the receiving orders upload rather than on their own — see Serial-tracked products.

Upload process¶

1. Select entity type¶

1. Select New Upload.
2. Select the Entity Type from the dropdown.
3. Review the guidelines shown for that type.

2. Upload your CSV file¶

You can start the upload three ways:

The file has to meet these requirements:

3. Validation¶

The system checks your file before processing it:

4. Processing¶

Once your file passes validation, the system creates a background job, processes each row in sequence, and logs any row-level errors as it goes. When it finishes, it generates a summary report.

Row limit and skipped rows¶

A single upload processes at most 2,000 data rows (the header row doesn't count). The limit applies the same way to CSV uploads and to rows extracted from a document.

Files larger than the limit are not rejected, and the extra rows are not discarded. The job processes the first 2,000 rows and records every remaining row as a Skipped result, so you can see exactly which records weren't captured and finish the import in a second upload.

What you see¶

When an upload exceeds the limit:

• A warning notification appears: "N rows not imported"
• An amber notice on the results view states how many rows the file contained, how many were processed, and which row numbers were skipped - for example, "This file has 3,000 data rows, but a single upload processes at most 2,000. The first 2,000 rows were processed; data rows 2,001 through 3,000 were skipped."
• Each skipped row appears in the results table with the status Skipped, keeping its original row number from your file
• The jobs list shows a Skipped (row limit) count on the job

The same notice appears later on the job's detail view, so you can return to a past upload and still recover its skipped rows.

Finishing the import¶

1. Open the upload results — from the upload modal, or by selecting the job in the jobs list.
2. Select Download skipped rows (CSV) in the amber notice, or Skipped Rows (Re-upload) in the Download Results panel.

The file downloads as <your-filename>-skipped-rows.csv, using the same columns and order as the upload template.

1. Upload that file as-is for the same entity type. No editing required.
2. Repeat if the remainder is still over 2,000 rows.

Downloading skipped rows requires bulk upload export permissions. The download is only available for jobs the row limit actually truncated.

CSV file requirements¶

General format rules¶

All CSV files must follow these standards:

column_name_1,column_name_2,column_name_3
value_1,value_2,value_3
value_1,value_2,value_3

Products CSV template¶

sku,name,description,barcode,unit_of_measure,weight,reorder_point,reorder_quantity,is_lot_tracked,is_serial_tracked
WIDGET-001,Blue Widget,Standard blue widget for testing,123456789012,EACH,1.5,10,50,false,false
DEVICE-002,Smart Device,IoT-enabled monitoring device,987654321098,EACH,2.0,5,20,false,true

Required fields:

• sku: Unique product identifier. Uppercase letters, numbers and hyphens only (for example WIDGET-001)
• name: Product display name

Those two are the only required columns — every other column below may be omitted entirely.

Optional fields:

Values the template suggests for the constrained columns:

• unit_of_measure: EACH, CASE, BOX, PACK, PALLET
• temperature_requirement: AMBIENT (room temperature), REFRIGERATED (35–45°F), FROZEN (below 32°F)
• preferred_location_type: FLOOR, RACK, SHELF, BULK
• storage_class: user-defined (for example A, B, FRAGILE). Must match a location's storage class restriction for putaway to consider that location
• Boolean columns accept true/false, yes/no or 1/0

Receiving orders CSV template¶

When you upload receiving orders, they become visible to your entire warehouse team, so several people can process different POs from the same import at once.

Each row is one line item. Header-level columns (the purchase order, carrier and equipment details) repeat on every row of the same order, or are left blank after the first row.

purchase_order_number,customer_name,carrier_name,expected_date,carrier_reference,product_sku,expected_quantity,unit_cost,lot_number,serial_number
PO-001,Acme Corp,FedEx,2024-01-20T10:00:00Z,TRUCK-ABC123,APP-SHIRT-001,100,8.99,LOT-001,
PO-001,,,,,ELEC-LAPTOP-001,1,1299.99,,SN-12345678
PO-002,Tech Solutions Inc,,2024-01-21T14:00:00Z,,ELEC-PHONE-001,25,899.99,,

Required fields:

• product_sku: Must match an existing product SKU in the warehouse
• expected_quantity: Number of units expected to receive

Those two are the only required columns. In particular purchase_order_number is optional — see the grouping note below for what happens when you leave it out.

Optional fields:

Values accepted by the constrained columns:

• priority: LOW, NORMAL, HIGH, URGENT
• equipment_type: TRAILER, CONTAINER, FLATBED, FLAT_RACK, LOWBOY, CHASSIS
• equipment_size: 20, 40, 45, 53
• expected_date: ISO 8601 with time (YYYY-MM-DDTHH:MM:SSZ)
• expiration_date: date only (YYYY-MM-DD)
• mbol_number and bol_number: maximum 50 characters

Grouping and validation:

• Rows are grouped into one receiving order by purchase_order_number together with carrier_reference — the same PO arriving on two different carrier references becomes two receiving orders.
• Rows with no purchase_order_number are not grouped with each other; each becomes its own receiving order under a generated placeholder reference. Supply the column whenever you want multiple line items on one order.
• The system checks that every product_sku value exists before processing.

Job history and permissions:

Receiving order uploads are retained permanently — you can review historical imports for audit purposes, see who uploaded which POs and when, and check upload status and validation errors. Admins and managers can upload receiving orders; all warehouse staff can view and process the uploaded POs, and the system tracks which user processed each one.

Serial-tracked products¶

Serial numbers have no entity type of their own. They are imported as an optional serial_number column on the receiving orders CSV, and the platform validates them while it validates the rest of the row.

Serial numbers on a receiving orders upload¶

purchase_order_number,product_sku,expected_quantity,serial_number
PO-2025-001,DEVICE-002,1,SN2025-001-0001
PO-2025-001,DEVICE-002,1,SN2025-001-0002
PO-2025-001,DEVICE-002,1,SN2025-001-0003

One row per unit. When a serial number is supplied, expected_quantity must be 1. A serial-tracked product with a quantity above 1 fails with "must have expected quantity of 1 when serial number is provided" - so three units of DEVICE-002 need three rows, as above.

Serial number validation¶

For products saved with serial tracking enabled:

Lot-tracked products¶

Lot numbers use the same pattern - an optional lot_number column on the receiving orders CSV. Lot tracking is more forgiving than serial tracking: a lot-tracked product with no lot_number produces a warning ("Lot number recommended"), not an error, so the row still imports.

Job management¶

Viewing upload history¶

The bulk upload page lists every upload job, with its ID and creation timestamp, entity type and file name, current status and progress, total records and success/failure counts, and an error download link for failed jobs.

Monitoring job progress¶

For large uploads:

1. The job appears in the jobs list immediately after upload.
2. Its status updates automatically as processing progresses.
3. Select the job row to see detailed progress.
4. Download the error report if any records failed.

Canceling jobs¶

1. Find the job in the jobs list.
2. Select Cancel (only available for pending or processing jobs).
3. Confirm the cancellation.

The job status changes to Cancelled. Records already processed before you cancelled stay in the system.

Error handling¶

Common validation errors¶

Row-level errors¶

If individual rows fail during processing:

1. The job finishes as Completed, even though some rows failed.
2. An error report listing the failed rows is generated.
3. Download the error CSV to identify the issues.
4. Fix the errors and re-upload only the failed records.

Error report format¶

row_number,error_code,error_message,original_data
5,DUPLICATE_SKU,Product with SKU 'WIDGET-001' already exists,"WIDGET-001,Premium Widget,..."
12,INVALID_BARCODE,Barcode '123' is not a valid UPC/EAN format,"WIDGET-005,Another Widget,..."

Getting it right¶

Test with 10-20 records before uploading thousands, and validate the file in a spreadsheet first. Remove special characters and extra spaces, save it as UTF-8, and always start from the downloaded template rather than typing headers by hand.

Schedule large uploads during off-peak hours, keep each file at or under 2,000 records — see Row limit and skipped rows — and upload in logical batches, by storage class or supplier, rather than one giant file. Try a trial upload in a test warehouse before running it in production.

Make sure SKUs, barcodes, and serial numbers are genuinely unique, fill in optional fields where you have the data for better reporting, keep formatting consistent throughout the file, and confirm every referenced product or warehouse actually exists.

For serial numbers, expand quantities into individual rows — a serial-tracked line must have expected_quantity of 1 — and use a consistent, sequential numbering scheme. Uniqueness is checked per SKU, so a mislabeled serial won't be caught as a duplicate; make sure each one sits on the correct product_sku. A serial number already in the system fails the row, so re-upload only the units that haven't been received yet.

Troubleshooting¶

Related guides¶

• Templates - Label and document template management
• Users - User permissions for bulk upload access
• Receiving Operations - Processing uploaded receiving orders

Support¶

For bulk upload assistance:

• Email: support@zoratech.io
• FAQ: Bulk Upload FAQ
• Troubleshooting: Common Issues