***

title: Bulk Upload Inventory
description: Learn how to import large volumes of inventory using your custom-tailored template.
---------------------

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.

# Bulk Upload Inventory

The Bulk Upload tool is the most efficient way to log large shipments or migrate existing data into the system. Our platform generates a custom template for you that includes all your organization's specific custom fields.

## Getting Started

To access the bulk upload tools, follow these steps:

1. Navigate to the [Inventory Dashboard](https://app.esoapp.co.uk/inventory).
2. Click the **Bulk Upload** button in the top action bar.
3. In the modal that appears, click **"Download Template"**.

<Callout intent="info">
  **Smart Templates:** The file you download is dynamically generated. It includes standard columns
  (weight, dimensions, etc.) plus any **Custom Inventory Fields** you have already defined in your
  settings (e.g., `PO Number`, `Container Number`).
</Callout>

***

## Field Mapping

The template uses specific headers to ensure data is placed correctly.

| Column        | Required | Description                                                           |
| :------------ | :------- | :-------------------------------------------------------------------- |
| `description` | Yes      | The name of the item (e.g., `Combiner Box - Aurora Basin`).           |
| `partNumber`  | Yes      | The manufacturer or internal part number.                             |
| `quantity`    | Yes      | Total units. Must be a whole number.                                  |
| `status`      | Yes      | Current state: `expected`, `available`, `in_transit`, or `delivered`. |
| `projectId`   | Yes      | The name or ID of the project.                                        |
| `dimensions`  | -        | `length`, `width`, `height` (use numbers only).                       |
| `custom.*`    | -        | Your specific fields like `custom.vessel_name` or `custom.PO_Number`. |

***

## Pro-Tips for Successful Uploads

* **Avoid Units in Cells:** If an item weighs $150 kg$, enter `150` in the `weight` column and ensure the `weightUnit` column is set to `kg`.
* **Multiple Barcodes:** If an item has multiple barcodes, separate them with a semicolon (`;`) in the `barcodes` column (e.g., `ABC-1:1;ABC-2:1`).
* **Clean Data:** Ensure there are no empty rows at the bottom of your CSV file to prevent processing errors.

<Callout intent="warning">
  If the `projectId` or `clientId` in your CSV does not match an existing record in the system
  exactly (including casing), the upload will pause to prevent orphaned data.
</Callout>

***

## Roadmap: Intelligent Mapping (v2)

We are currently developing **Bulk Upload v2**, designed to make data entry even faster by removing the need for strict template adherence.

### What's coming in v2:

* **Relaxed Headers:** Upload a CSV from any supplier or carrier without re-formatting it to our template first.
* **AI-Powered Mapping:** The system will automatically detect which of your columns match our system (e.g., mapping "Serial #" to "partNumber").
* **Review & Confirm:** You'll see a preview of the mappings to confirm or correct any detections the system missed.
* **Machine Learning:** The system **learns your preferences**. If you manually map a specific supplier's header once, the system will remember it and automate the mapping for every future upload from that supplier.