Skip to main content

Import suppliers from a spreadsheet

The spreadsheet importer is the fastest way to create or update many suppliers at once. It runs in four steps inside a single dialog: upload your file, map each column to a supplier field, validate and preview exactly what will change, then import as a background job that reports created, updated, and failed counts. Nothing is written until the final step, so you can validate as many times as you like first.

To add a single supplier, use the Add Supplier button on the list instead. To pull your existing suppliers out as a spreadsheet — which doubles as a bulk-edit template you can re-import — see Export suppliers.

Before you begin​

  • You need the suppliers.import permission. Without it the Import button is hidden and every import endpoint is blocked.
  • Warehouses, stores, payment terms, tax rates, and supplier pricing tiers referenced by your file must already exist in your account — the importer matches them by name and, if it can't find a match, warns and leaves that field blank (it never creates them for you). Set them up first in Settings.
  • Supplier names are globally unique. That's what lets a row without an id update an existing supplier when the Name matches — see How the importer decides update vs create.
  • A supplier's currency is carried by its pricing tier, so you set currency by importing a default_pricing_tier value — there is no separate currency column. See Set tax rate and currency in bulk.

Open the importer​

On the suppliers list, click Import (top right). The Import Suppliers dialog opens on Step 1 with a four-step indicator: Upload → Map Columns → Validate → Import.

There is no template to download for suppliers. Prepare any spreadsheet with a header row (the importable columns reference lists every accepted column), or start from an export of your existing suppliers.

Step 1 — Upload your file​

Provide your data in one of three ways: drag a file onto the drop zone, click Choose File, or paste CSV/TSV text into the box. Accepted file types are .csv, .tsv, .txt, .xlsx, and .xls.

  • The delimiter (comma, tab, or semicolon) is auto-detected; when you paste, you can override it with the Column separator toggle.
  • The importer guesses whether your first row is a header and sets the First row is a header checkbox accordingly — confirm it's correct.
  • A Raw Data Preview shows the first few rows so you can check the file parsed cleanly. Click Next: Map Columns.

Step 2 — Map your columns​

Each column from your file is listed with a Maps To dropdown. The importer auto-matches columns whose header equals a field's key or label (case- and spacing-insensitive), but you can override any mapping or leave it as Skip this column.

The Name field is required: if no column is mapped to Name, a warning shows and you can't continue. Every other field is optional.

The mapping targets are the supplier fields listed in the importable columns reference, including the two lookup columns that carry a supplier's tax and currency defaults:

  • Default Tax Rate — the supplier's default tax rate, matched by tax-rate name (for example GST 10%).
  • Default Pricing Tier — the supplier's default pricing tier, which carries its currency. It matches either the tier's plain name or its display name (for example Supplier USD (USD)).

A Mapped Data Preview shows the first five rows as they'll be sent. Review it, then click Next: Validate.

Step 3 — Validate and preview​

Validation resolves every lookup name to a record and classifies each row as New or Update, all without writing anything. It runs as a background job, so it's safe to run repeatedly. You get a summary bar (New, Updates, Errors, Warnings) and a per-row table with filter tabs (All / Valid / Errors / Warnings).

  • Rows with errors are highlighted and can't be imported; rows with only warnings import fine.
  • If some rows were skipped before validation (because a required value like Name was blank in an unmapped or empty column), a warning banner tells you — go back to Map Columns and check your mapping if that was unexpected.

Fix the source file and re-validate, or proceed to import just the valid rows.

How the importer decides update vs create​

For each row the importer looks for an existing supplier in this order:

  1. By ID — if you mapped an ID column and the row has a value, it matches the supplier with that database ID. A non-numeric ID, or an ID that doesn't exist, is a row error.
  2. By Name — otherwise it matches an existing supplier whose Name equals the row's Name (case-insensitive). Because supplier names are globally unique, a match means Update and no match means New.

When a new supplier is created, the importer also creates its default warehouse automatically (and an owned address when address columns are present). If you also map a default_warehouse column, your value takes precedence.

Lookups resolve names, and warn instead of failing​

Five columns resolve a value to a record that must already exist: default_warehouse, default_store, default_payment_term, default_tax_rate, and default_pricing_tier. Matching is by name, case-insensitive.

Unlike a hard lookup, an unmatched value here is a warning, not an error — the row still imports, and that one field is left blank. This keeps a large import from failing wholesale over a single misspelled warehouse name. Check the Warnings tab after validating to catch any values that didn't resolve.

  • default_pricing_tier matches either the tier's name or its display name (Supplier USD (USD)), so a value copied from an export resolves cleanly.
  • A blank lookup cell leaves the field unchanged on an update.

Step 4 — Import as a background job​

Click Import N Suppliers on the preview to queue the run. It runs as a background job, so you can keep working; the dialog shows progress and the final Processed / Created / Updated / Errors counts when it finishes.

Set tax rate and currency in bulk​

The most common reason to import suppliers is to set the Default Tax Rate (for example GST) and currency across many suppliers at once. Because currency is carried by the pricing tier, the round-trip is:

  1. Export your suppliers to a spreadsheet. The export already contains a Default Tax Rate column and a Default Pricing Tier column (with values like Supplier USD (USD)).
  2. Edit those two columns in the file — set the tax rate name and the pricing tier for each supplier.
  3. Import the file back in. Map Default Tax Rate and Default Pricing Tier on the Map Columns step, then validate and import.

The export and import use the same labels for these two columns, so the values round-trip without reformatting.

For a handful of suppliers you don't need a file at all: turn on the Default Tax Rate and Default Pricing Tier columns in the list's Column Selector, switch to grid view, and edit them inline from a dropdown — or edit a single supplier on its detail page. See The suppliers list: columns.

Next steps​

Video transcript

Need many suppliers at once? Import them. On the suppliers list, click Import. Paste your rows or upload a file, then map each column. Only Name is required. Validate first — nothing is written until you import. The rows run as a background job. Supplier names are unique, so re-importing an edited export updates records instead of duplicating them.

Last verified: