> ## Documentation Index
> Fetch the complete documentation index at: https://docs.garmentflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Importing master data

> Bulk-import your customers, vendors, fabric and accessory masters, and units of measure from CSV files — plus a separate importer for a customer's brand colour palette.

The **Data Import** wizard lets an administrator load your
<Tooltip tip="A shared reference list — fabrics, accessories, colors, units, body parts, or categories — that styles, BOMs, and purchase orders read from.">[master data](/reference/glossary#master-catalog)</Tooltip>
in bulk from spreadsheet (CSV) files, so a new workspace is ready in hours
instead of being entered by hand. It validates every row before saving, never
overwrites data you've already entered, and tells you exactly which rows to fix
when something's wrong.

You'll find it as **Data Import** in the **Settings & Config** sidebar group.
It's available to administrators.

For the on-screen reference — what each catalog holds, the bilingual name
fields, and how the catalogs feed BOMs, cost sheets, and purchase orders — see
[Master catalogs](/admin/master-catalogs).

## What you can import

The wizard handles five kinds of master data. A separate importer on the same
page loads a **customer's brand colour palette**; the workspace's shared
colour list is not imported through this wizard (it is edited from Masters →
Colours).

| Entity                                                                                                                                                                                                                      | What it covers                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Customers**                                                                                                                                                                                                               | The buyers you sell to, with their default terms.                                             |
| **<Tooltip tip="The canonical record for one outside party — a garment factory, a fabric mill, or an accessory supplier — your workspace places orders with.">[Vendors / Factories](/reference/glossary#vendor)</Tooltip>** | Factories and suppliers, each typed as a garment factory, fabric mill, or accessory supplier. |
| **Fabric masters**                                                                                                                                                                                                          | Your catalog of fabrics (main materials).                                                     |
| **Accessory masters**                                                                                                                                                                                                       | Your catalog of trims and accessories.                                                        |
| **Units of measure**                                                                                                                                                                                                        | Units of measure (such as yards or pieces).                                                   |

### Import in dependency order

Some records refer to others. The wizard shows a **Recommended setup
order** notice for this reason:

1. **Customers, vendors, and units first.** These stand on their own; a
   <Tooltip tip="The canonical record for one fabric, with its vendor, category, unit, and lead time.">[fabric master](/reference/glossary#fabric-master)</Tooltip>
   or
   <Tooltip tip="The canonical record for one trim or accessory, with its vendor, category, unit, and lead time.">[accessory master](/reference/glossary#accessory-master)</Tooltip>
   can name a vendor that must already exist.
2. **Fabric and accessory masters second.** They reference vendors,
   categories, and units.
3. **Material colours after masters.** Each fabric or accessory master
   holds its own colours, added from the master's own page.
4. **The customer brand palette any time.** The separate importer at the
   bottom of the page loads a customer's brand colours (customer name,
   colour code, name, Pantone).

Categories and units named on a master row are an exception — see
[minted on reference](#minted-on-reference) below.

## Preparing your data

For each entity, **download the template** from the wizard. The template is a
CSV with the correct column headers and a couple of sample rows. Fill in your
data under those headers — keep the header row exactly as provided.

### The match key

Every entity has a **match key** — the column the wizard uses to tell whether a
row is a new record or one that already exists:

| Entity              | Match key    |
| ------------------- | ------------ |
| Customers           | `name`       |
| Vendors / Factories | `name`       |
| Fabric masters      | `article_no` |
| Accessory masters   | `item_code`  |
| Units of measure    | `code`       |

For fabric and accessory masters the match is **normalized**: hyphens, spacing,
and letter case are ignored, so `RI-026A` and `RI026A` are treated as the same
item. Everyone else matches on the plain name or code, ignoring case and
surrounding spaces.

### Columns by entity

The tables below list each column and whether it's required. Anything not
marked required is optional.

**Customers** — match key `name`:

| Column                        | Required | Notes                        |
| ----------------------------- | -------- | ---------------------------- |
| `code`                        | Yes      | Unique customer code         |
| `name`                        | Yes      | Customer or brand name       |
| `country`, `address`, `notes` | No       | Contact and free-text detail |
| `payment_terms_days`          | No       | Net payment days (e.g. 30)   |
| `default_trade_term`          | No       | Default Incoterm (e.g. FOB)  |
| `default_destination`         | No       | Default ship-to destination  |

**Vendors / Factories** — match key `name`:

| Column                                           | Required | Notes                                                     |
| ------------------------------------------------ | -------- | --------------------------------------------------------- |
| `name`                                           | Yes      | Vendor or factory name                                    |
| `vendor_type`                                    | Yes      | `GARMENT_FACTORY`, `FABRIC_MILL`, or `ACCESSORY_SUPPLIER` |
| `code`, `country`, `address`                     | No       | Identification and location                               |
| `contact_name`, `contact_email`, `contact_phone` | No       | Primary contact                                           |
| `currency`, `payment_terms`                      | No       | Commercial defaults                                       |

**Fabric masters** — match key `article_no`:

| Column                                                                                         | Required | Notes                                                         |
| ---------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------- |
| `article_no`                                                                                   | Yes      | Article number (match key, normalized)                        |
| `description`                                                                                  | No       | Legacy display description                                    |
| `name_en`, `name_zh`                                                                           | No       | English and Chinese names                                     |
| `content`, `finish`, `weave`, `weight`                                                         | No       | Fabric specification                                          |
| `width_inches`, `gsm`                                                                          | No       | Width and weight per area                                     |
| `lead_time_days`, `moq`, `mcq`                                                                 | No       | Sourcing terms                                                |
| `standard_cost`, `currency`                                                                    | No       | Cost and its currency                                         |
| `min_stock_qty`                                                                                | No       | Reorder level                                                 |
| `vendor`                                                                                       | No       | Fabric mill name or code (must already exist)                 |
| `category`, `unit`                                                                             | No       | Created automatically if new                                  |
| `quote_vendor`, `quote_price`, `quote_currency`, `quote_purchase_unit`, `quote_conversion_qty` | No       | Optional supplier quote — the vendor named must already exist |

**Accessory masters** — match key `item_code`:

| Column                                                                                         | Required | Notes                                                         |
| ---------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------- |
| `item_code`                                                                                    | Yes      | Item code (match key, normalized)                             |
| `item_name`                                                                                    | Yes      | Item name                                                     |
| `name_en`, `name_zh`                                                                           | No       | English and Chinese names                                     |
| `supplier_code`                                                                                | No       | Supplier's own item reference                                 |
| `requires_color_matching`                                                                      | No       | `true` / `false` (default `true`)                             |
| `colour`, `size_spec`                                                                          | No       | Description                                                   |
| `moq`, `lead_time_days`                                                                        | No       | Sourcing terms                                                |
| `min_stock_qty`                                                                                | No       | Reorder level                                                 |
| `vendor`                                                                                       | No       | Accessory supplier name or code (must already exist)          |
| `category`, `unit`                                                                             | No       | Created automatically if new                                  |
| `quote_vendor`, `quote_price`, `quote_currency`, `quote_purchase_unit`, `quote_conversion_qty` | No       | Optional supplier quote — the vendor named must already exist |

**Units of measure** — match key `code`:

| Column        | Required | Notes                  |
| ------------- | -------- | ---------------------- |
| `code`        | Yes      | Unit code (e.g. `YDS`) |
| `description` | No       | Description            |

### A note on file encoding

Save your file as CSV. UTF-8 is recommended, but files saved from a
Chinese-locale copy of Excel (Big5 or GBK) are also accepted — the wizard
detects the encoding for you, so Chinese names import correctly either way.

## Two import modes

The wizard offers two modes. Choose the one that matches what you're doing:

* **Create only** — a row that matches an existing record is reported as an
  error. Use this for **initial onboarding**, when the workspace is empty and
  every row should be new.
* **Fill blanks** — for rows that match an existing record, only the **empty**
  fields are filled in; a field that already has a value is **never**
  overwritten. Use this to **enrich existing records** — for example, adding
  lead times or vendors to masters you imported earlier.

There is no mode that overwrites populated data, by design.

## Running the import

1. Open **Data Import** from the **Settings & Config** sidebar group.
2. **Pick the entity** you're importing from the "What are you importing?"
   dropdown.
3. **Download the template** and fill it in with your data.
4. **Choose the mode** — **Create only** or **Fill blanks**.
5. **Upload** your completed file.
6. **Preview** — the wizard parses and validates every row without saving
   anything yet (see below).
7. **Fix any errors** and re-upload until the preview is clean.
8. **Commit import.** The wizard writes the data and shows a summary of how
   many records were created, enriched, and added by reference.

## Reading the preview

The preview validates your whole file **before anything is saved**. Above the
row table you see the total rows, how many will be created, how many will be
enriched, and the error count. Each row shows its number, its status
(**Create**, **Enrich**, or **Error**), and the message — which column and
what is wrong.

The import is **all-or-nothing**: if even one row has an error, nothing is
saved. Fix the flagged rows in your file and upload it again. This means you
never end up with a half-imported file to untangle.

### Minted on reference

On a master row, the `vendor`, `category`, and `unit` columns refer to other
records by name or code:

* A **vendor must already exist** — that's why you import vendors before
  masters. A master naming an unknown vendor is reported as an error.
* A **category or unit is created automatically** if it doesn't exist yet —
  this is "minting on reference". A unit created this way is identical to one
  you'd import through the units template, so you don't have to pre-create
  every category and unit by hand. The result summary reports how many
  categories and units were minted.

## Customer colour palette (separate importer)

At the bottom of the same Data Import page, a **Customer colour palette**
card holds a separate importer for a customer's brand colours — customer,
colour code, colour name (English and Chinese), and Pantone. Same
all-or-nothing preview-then-commit shape as the entity wizard above, with its
own template.

The customer palette is customer-scoped: a colour imported here belongs to
one customer's brand palette and is picked from that customer's records
downstream. Material colours (colours owned by a fabric or accessory master)
are added from the master's own page, not through either importer here.

If your workspace does not show this card, your administrator has left the
capability off; there is a toggle for it on
[Feature settings](/admin/feature-settings).

## After the import

* **Verify the counts.** The result summary tells you how many records were
  created and enriched — check it against what you expected from your file.
* **Spot-check a few records** in the relevant module to confirm the data
  landed where you expected.
* **Continue in order.** If you're onboarding from scratch, run customers,
  vendors, and units, then the fabric and accessory masters — so each
  step's references are already in place.

## Related pages

* [Setting up your tenant](/admin/setting-up-your-tenant)
* [Master catalogs](/admin/master-catalogs)
* [Vendors](/admin/vendors)
* [Feature settings](/admin/feature-settings)
* [What changed in v5](/getting-started/what-changed-in-v5)
* [Styles module guide](/modules/styles)
* [Production module guide](/modules/production)
* [Tech Packs](/modules/tech-packs) — importing masters first means BOM
  rows on a tech pack review can link to existing materials.