Skip to main content
Uploading a file is the fastest way to bring many products into MerchantOps at once — a spreadsheet export from your PIM, ERP, or another catalog becomes a batch of products. This page explains the two upload paths, how columns map to product fields, and how to read the result.
If your data lives in a spreadsheet, export it to CSV first — or use the Excel re-importer below, which reads .xlsx directly. Pipe-delimited cells let a single column carry multiple values.

​
Two upload paths

They look similar and share a column format, but they behave differently. Pick deliberately.
Do not put a Standard Excel export through the CSV tab. The CSV path parses product rows only — every variant row in the file is silently dropped, with no error and no mention in the result. Use Import Products (Excel) for round-trip files.

​
The file

Your file needs a header row. A few columns are required; the rest are up to you.

​
How columns map

MerchantOps maps your columns automatically — there is no mapping dialog to fill in on this path.
1

System columns map to product fields

key, productType, source, and isPublished set the product’s core fields. Common headers are recognized case-insensitively and in a few spellings — for example Product Type, product_type, and productType all resolve to the product type.
2

Every other column becomes an attribute

Any column that isn’t a system column is stored as a product-level attribute, keyed by the column name — brand, description, color, material, and so on.
3

Pipe-delimited cells become multi-value

A cell like Red|Blue is split into a list of values. Use this for any attribute that holds more than one value.
Two behaviors are specific to the Excel re-importer:
  • Type coercion. Values are converted to the type each property definition expects — TRUE, Yes, and 1 all become a real boolean, for example. The CSV tab stores what it read: a spreadsheet TRUE stays the string "TRUE".
  • Conversely, brand auto-registration is specific to the CSV tab: brands that are new to a CSV upload are registered as brands automatically, so you don’t have to create each one up front. The Excel re-importer does not do this.

​
Unknown product types behave differently per path

This is the sharpest difference between the two paths.
The CSV tab does not check that the product type exists. A row naming a product type your organization doesn’t have still imports, and the resulting product carries a product-type reference that points at nothing — so it has no attribute template, and nothing tells you at upload time. Check your spelling against product types before you upload.
The Excel re-importer does check. Rows naming an unknown product type are rejected individually and reported with a “did you mean?” hint when a close match exists; the remaining valid rows still import.

​
Variant rows (Excel only)

The Standard Excel export writes one row per product and one row per variant. On re-import, a row with row_type set to variant and a parent_key naming its product creates or updates that variant instead of a product:
  • The parent must be a product row in the same file or a product that already exists. Otherwise the variant row errors.
  • Variants inherit their parent’s product type.
  • The 250 cap counts products, so a product with many variants doesn’t eat the limit.

​
Re-importing to update existing products

By default every valid row creates a new version of the product. To overlay your edits onto what’s already there instead, use Merge only provided columns:
  • It is pre-checked in the Import Products (Excel) dialog — that dialog exists for the export → edit → re-import loop.
  • It is off by default on the CSV tab and in the JSON import dialog; tick it yourself if you want merge behavior there.
With it on, a row whose key matches an existing product overlays only the columns present in your file onto that product’s latest version, preserving every other field, and adds a new version. A row that changes nothing is skipped rather than re-versioned. Keys that don’t exist yet are still created normally.
Merge is ignored when enrichment options are enabled on the upload — those rows go through the normal create-and-enrich path instead. On the CSV tab the enrichment options are on by default, so merge does nothing there until you turn them off. The Excel re-importer never enriches, so merge always applies.

​
Reading the result

The upload returns a per-row report: the total rows submitted, how many were created, how many failed, and a per-row error list (row number, product key, and reason) so you can fix a source file and re-upload just what failed. An Excel import also reports how many variants it created or updated.
The CSV and Excel uploads report no skip count. In merge mode, a row that was skipped as unchanged is counted under created — so created means “row accepted”, not “new version written”. Only the JSON import reports skipped rows separately.
Rows are reported by their position in the file, counting the header as row 1. When you correct errors, match the row numbers in the error list against your original file. If you enable enrichment options on the upload, each new product is queued for enrichment — Lakehouse search, brand-site scraping, or content generation — and that work is tracked as a Job you can watch after the upload returns.

​
Display groups on property imports

Products validate against property definitions, which are organized into display groups. When you import property definitions by CSV, any display group named in that file that doesn’t yet exist is created for you. (This applies to the property-definition import, not to the product upload described above.)

Exporting products

The other half of the round trip: producing the file you edit and re-import.

Recurring imports

How a scheduled feed from another system is set up.

Jobs

Watch enrichment progress after an upload.

Product types & properties

The templates and attribute schema your rows map onto.

How enrichment works

What happens when you enable enrichment on an upload.