***

title: Bulk Upload v2
description: How to import large quantities of inventory items in one go using CSV or XLSX files.
---------------------

For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.esoapp.co.uk/guides/inventory/llms.txt. For full documentation content, see https://docs.esoapp.co.uk/guides/inventory/llms-full.txt.

The bulk upload v2 feature lets you import hundreds or thousands of inventory items at once from a spreadsheet. The platform uses a two-step **validate → commit** workflow to ensure your data is correct before it is saved.

## Supported formats

| Format                | Max file size |
| --------------------- | ------------- |
| CSV (comma-separated) | 2 MB          |
| XLSX (Excel)          | 10 MB         |

***

## The upload workflow

### Step 1 — Upload your file

Navigate to **Inventory → Bulk Upload v2** and select your file. If you are using XLSX and your file has multiple sheets, you will be asked to choose which sheet to import from.

### Step 2 — Map columns

The platform analyses your file's columns and suggests mappings to the standard inventory fields and any custom fields your organisation has defined. You can:

* Accept a suggested mapping as-is.
* Change the target field for any column.
* Apply a **transform** to convert raw values (e.g. treating `0` as `false` for a boolean field, or parsing a combined dimension string like `100x50x30`).
* Skip a column entirely.
  Column mappings are remembered across uploads. If you upload a file with the same column names in the future, the platform will pre-populate your previous choices.

### Step 3 — Validate

Click **Validate** to run all data checks. The platform will flag:

* Missing required fields.
* Values that don't match a field's type or allowed options.
* Duplicate part numbers (within the upload itself, or against existing items).
* Values that fall outside a configured `min`/`max` range.
  Each row is shown as either **valid** (green) or **invalid** (red) with a description of what needs to be fixed. You must resolve all errors before proceeding.

### Step 4 — Commit

Once all rows are valid, click **Import** to create all the inventory items in one atomic transaction. The session token issued at the end of validation is consumed on commit, so the same validated set cannot be imported twice.

## CSV template

Download the **Upload Template** from the inventory page to get a pre-formatted CSV that matches the standard fields for your organisation. The template includes column headers for all system fields and any custom fields that have been defined.

## Tips

* Set a **default project**, **client**, and **location** during the mapping step so you don't need a column for each one in every file.
* Use the **dimensions triplet** transform if your spreadsheet stores length, width, and height in a single column (e.g. `100x50x30 cm`).
* The platform learns from your corrections — if you remap a column that was auto-suggested incorrectly, that correction will be used next time.