Imports

An import loads a spreadsheet into your catalog, so you can add or change hundreds of products at once instead of opening them one by one.

An import reads a spreadsheet and writes what is inside it into your catalog. You give the PIM a CSV or an XLSX file. You tell it which column of your file feeds which field, and it works through your rows one at a time. When it finishes you get a copy of your own file back with two extra columns saying what happened to each row.

Most people import for one of three reasons. The first is to load your catalog into the PIM. The second is to change hundreds of your products at once instead of opening them one by one. The third is to send back a file you exported and edited in a spreadsheet. An import can add records, change records, empty chosen fields on records, or delete records, and you pick which of those four it does.

You will find all of this under Uploads, in the Imports tab. The Create import button above the table opens a dialog over the page that takes you through the file. The table under it lists every import your team has run, with a status and four counters on each one.

One file writes one kind of record. You choose from eight kinds, and products is where most people start.

Before you start

Three things matter before your first import. Everything else on this page can wait until you need it.

What your role lets you do

Below Manager, the Create import button above the table is not shown to you at all. You can still open any import in the table and download its Results file. Roles are set in team, roles and permissions.

An Editor on your team is the case that surprises people. An Editor can export but cannot import, so an Editor sees a Create export button on the Exports tab and no Create import button here.

There is no undo

Nothing shows you which rows would fail before you run it either. You find out after the fact, from the Results file, once the writing has already happened. So import a handful of rows first, read the Results file, fix whatever it flags, and only then send the whole thing. A 20-row test costs you two minutes and is the only preview there is.

Import in the right order

Your file can only point at categories and specifications that already exist. Import a products file naming a category you do not have and the product goes in without that category. The PIM will not invent a place in your category tree from a cell in a spreadsheet. Brands and tags are different: those two are flat lists of names, so a products import can create them for you.

To load a catalog from nothing, work in this order:

1. Categories
2. Spec groups
3. Spec definitions
4. Spec values
5. Products

How to import a file

1. 1

   Open the import dialog

   From Uploads, select the Imports tab and click Create import above the table.

2. 2

   Choose what you are importing

   The first screen inside the dialog is called Entity. It shows eight cards, one for each kind of record. Click Products, or click whichever card matches your file.

3. 3

   Add your file

   On File, drag your file onto the drop area, or click Upload new to pick one from your computer. A preview of your first rows appears under it once the file is read.

4. 4

   Pick the mode

   Mode shows four cards. Click Create to add records that are not in your catalog yet.

5. 5

   Map your columns

   Columns lists your catalog’s fields down the left. Each field has a dropdown on the right with your file’s column names in it, so pick the column that feeds it. Anything the PIM recognized is already filled in for you.

6. 6

   Set the options

   On Options, decide what should happen to a row that names a brand or a category you do not have. You can leave everything here alone the first time.

7. 7

   Check the summary and submit

   Summary lists back everything you chose. Read it, then click Submit in the bottom right of the dialog.

That is the whole flow. Your import appears at the top of the table right away and moves through a few statuses while it runs. It ends with a count of successful rows, warnings, errors and blocked rows. A small message pops up wherever you are in the app when it finishes.

Everything below explains those screens one at a time, and then how to read what came back. You do not need any of it for a first import of a small file.

Every option in detail

The dialog has eight screens in total: Entity, File, Mode, Match Rules, Columns, Options, Clean Fields and Summary. You never see all eight, because the mode you pick decides which ones apply to you.

Clean and Delete skip both Columns and Options, so in those two modes the values inside your cells are never read at all. Only the columns your match rules point at matter. The Tags card never shows Options in any mode, because a tag has nothing to configure.

The step markers along the top of the dialog only take you backwards. Next is in the bottom right and stays gray until the screen you are on is complete, and the sections below say what each screen counts as complete.

Nothing you set up is saved anywhere, so reloading the page loses the whole setup and puts you back on Entity. Closing the dialog asks you to confirm first, with Discard and Keep editing, and discarding deletes the file you uploaded. While a submit is in flight the dialog will not close.

Step 1: Choose what you are importing

Entity shows eight cards. Each card is one kind of record, and your file writes that kind and nothing else. Change this card later and you reset every screen after it.

If you are not sure which of the last three you want, specifications explains what a group, a definition and a value each are.

Step 2: Add your file

File is where your spreadsheet goes in. Drag it onto the drop area, or click Upload new to browse your computer. If the file is on the web instead, click From URL next to it. A small dialog opens with a URL field, and pasting a direct download address there fetches the file.

A bar shows your upload moving, and a preview table appears once your file has been read. You see at most 10 rows of it, however many your file has. The preview is there to prove the PIM read your file the way you expected, not to show you your data.

Three controls are above that preview, and Next turns on once the preview has found at least one column in your file.

Leave First row is a header on unless your file genuinely has no header row. Turning it off renames every column to Column A, Column B and so on. The later screens then map against those names. Because the names change, turning the switch off clears any match rule and any column mapping you had already set.

Step 3: Pick the mode

Mode shows four cards. The mode decides whether your rows create something, change something, empty something or destroy something.

Pick Create for a catalog you are loading for the first time, and for any file where every row is genuinely new. Pick Update when the records already exist and you want to change some of their fields. It is also the safe choice for a second attempt after a partly failed Create. Pick Clean when you want fields emptied and cannot express that in a cell, because an empty cell means “leave this alone” and never means “clear this”. Pick Delete only when you are certain, because nothing brings the records back.

Change the mode later and you reset every screen after it.

Delete a product and you lose its variants, along with its specification values and its category, tag and asset assignments. Nothing stops you deleting a product or an asset.

The other six kinds have a guard. A brand, category, tag, spec group, spec definition or spec value will not delete while something in your catalog still points at it. You get one error per row saying what is still attached. Detach those records first, or merge the record from your catalog instead.

How much one delete row removes depends on what it matched. A product has variants underneath it. Matching on a variant identifier and matching on a product identifier are two different instructions.

Step 4: Match your rows to records

Match Rules is how the PIM finds the record each of your rows is talking about. Create never touches a record you already have, so it never shows this screen. The other three modes all do, and none of them can run until you fill this in.

A rule pairs a target with one column of your file. The target is what kind of thing to look up, and the column is where your value comes from. Each rule is on its own card, labeled Rule 1, Rule 2 and so on.

Your rules run top to bottom, and the first one that finds exactly one record is the one that applies. That is why the order matters and why you can drag the cards.

Use Single Match with the most specific column you have. A SKU or an ID identifies one record on its own. A single rule on either is all your file needs in most cases. Use Compound Match when no single column is unique in your catalog. In practice that means matching a product by SKU plus brand name, because the same supplier SKU turns up under two brands in your catalog. Switch a rule to Compound Match and the usual shape for that card is filled in for you.

Which targets you can pick depends on the card, and two of them behave differently from the rest.

Category Path walks your tree from the top, so a cell reading Electronics > Phones finds the child and not just anything called Phones. Asset URL accepts both the address an export writes and the public address you see in the catalog. It ignores everything after the question mark in either, so a stale address in your file still resolves.

Three rules the dropdowns enforce for you, so that a rule you can build is a rule that can work:

• ID never appears in a compound rule. An ID already identifies one record, so adding a second target to your rule can only narrow the result to nothing.
• A compound rule always keeps one identifying target. A rule made only of Brand Name would match every product of that brand. While your rule has no identifying target, the dropdown gives you nothing else and the button that removes the last one is hidden.
• The same target cannot appear twice in one rule. A target already used by another row of your card disappears from the dropdown.

Up to 2 rules are already set up when you first open this screen. Your column names are compared against a list of names the PIM knows, ignoring capital letters and punctuation. So Product ID, product_id and PRODUCT-ID all go to the same target. If nothing is recognized you get one empty rule with a sensible target and a blank column for you to fill.

The id and variant_id columns an export writes are not fields you can map on Columns, and they do not need to be. Leave them in your file, point a rule at the ID target, and their values are read right out of the row. Either column finds your parent product.

A rule you have not finished shows its problem on the card, in red, and Next stays off until every card is clean.

Step 5: Map your columns

Columns is where you connect your file to your catalog. It lists your catalog’s fields down the page, in groups with a heading over each one, and every field has a dropdown to its right with your file’s column names in it. You read it field to column, not column to field, so the list on the page is your catalog and not your spreadsheet.

The PIM fills in as much as it can the moment you arrive. Each of your column names is compared against a field’s internal name, its English name, its name in your own language, and a list of older names. Capital letters and punctuation are ignored. The first field that matches takes it and each of your columns is used once. Nothing is matched loosely, so a column either matches or it does not, and a near miss like Prod Title stays unmapped.

The reverse is true as well. A column you did map is read as the field you picked, whatever its header says. Point a column of descriptions at Price and every row fails on the price rules.

A toolbar is pinned above the list. It has a search box that narrows the list as you type. The chips beside it filter the list down to the fields you have mapped, or the ones you have not. Those chips count over the whole list and not over what you can see, so they double as a read-out of how far along you are. If a filter is hiding a field you still have to map, an orange line under the toolbar tells you so.

Each field shows what it needs from you.

Next turns on once you have mapped at least one column and every field the mode requires.

The other three modes require nothing because your match rules already found the record. Update still has to map something. The screen will not advance while every field reads Not mapped, because an update that writes no field does nothing.

These are the fields a products file can write into.

You write per-currency prices inside a single cell, as USD=29.99|EUR=27.50. The currency matching your organization’s default becomes the main price and the rest become per-market prices beside it.

Three columns are hidden from this screen in every mode, so you cannot map them even if your file has them. Supplier Cost and Supplier Stock are written by your data sources, and On-hand Stock is added up from your connected locations. Inventory sets out where each number comes from.

Step 5: What an empty cell does

An empty cell and a missing column are not the same thing, and the difference decides whether an update leaves a field alone or wipes it.

So a blank cell never clears anything. If clearing a field is what you actually want, that is what Clean mode is for.

One more thing about numbers. In a money or dimension cell a comma is read as a thousands separator and removed before the number is read. So 1,5 arrives as 15, and 0,00 arrives as a zero that clears the column. Write 1.5 with a period instead, or use the per-currency form EUR=1.5, which is read the same way.

Step 6: Set the options

Options decides how the PIM should behave in the cases your file did not cover. Most of it is questions with radio buttons, and the defaults are chosen so that nothing is created or destroyed behind your back. You can leave the whole screen alone on a first import.

Missing references decides what happens to a row naming something you do not have. Each question gives you Skip with warning, Create automatically and Fail the row, in that order. A question about a category or a specification drops the middle one.

Skip with warning imports the row without that one reference and records a warning against it. Fail the row rejects the row. Create automatically makes the missing brand or tag by name, and you only get that choice on those two. A brand and a tag are just names. A category or a specification has a place in a structure the PIM cannot guess.

Set every question to Fail the row when you re-import a file you exported. Nothing in that file should be missing. A question answered Skip with warning would let a real problem through with no message, and Fail the row shows it to you.

Two of these questions behave differently from the rest. A Spec Definitions row naming a group you do not have is dropped whole, even under Skip with warning. So is a Spec Values row naming a definition you do not have. There is nothing left of either row once the parent is gone. Setting those two to Fail the row only changes what the report calls it.

Update behavior controls every field that takes more than one value at once, such as the brands, categories, tags and specification values on a product. It appears on the Products, Spec Groups, Spec Definitions and Assets cards in Update, and on Assets in Create.

Choose Replace when your file is the complete picture, which it is whenever you exported, edited and re-imported. Choose Append when your file only names the things you want to add, such as one new tag per product. Choose Keep existing when you are filling gaps and must not touch anything already filled in.

It does not cover images. Primary Image URL, Gallery Image URLs and Resource URLs always replace, which assets explains from the library side. Append also behaves differently on a specification that allows only one value. Your file’s value is rejected and the existing one is kept, and the rest of the row still saves with a warning.

Asset downloads decides what a broken image address costs you. It appears on the Products, Brands and Categories cards in Create and Update.

Leave Warn and continue on unless a product with a missing image is worse to you than no product at all. Picking Fail row on a products file rejects the whole product, so that row comes back as an error and the other rows of the same product come back as blocked.

If an asset already exists decides whether a file you already have gets used again. The PIM compares the contents of the file, not its address. So re-importing the same picture from a different link still finds it. On the Products, Brands and Categories cards you get Reuse existing, which is the default, and Upload as new. A standalone Assets import in Create gets three choices instead, because that file has its own display name and alt text. Reuse, update labels is the default, Reuse, keep labels leaves the old wording alone, and Upload as new makes a second copy.

Array value separators sets the character that splits a cell with a list in it. Each box takes up to 3 characters, and clearing a box puts the default back. Next stays off while any box looks empty. Change one only when your own data contains the default character, which is the one case where the default would split a value in half.

Two separators default to >: Specs path and Category path. The other fourteen default to |: Tags, Features, Specs, Category list, Brands, Barcodes, ISBNs, Part Numbers, Gallery, Resources, Websites, Information sources, Custom identifiers, and Excluded categories.

The = between a label and a value in a pair-style cell, such as UNSPSC=43211503, is fixed and nothing here changes it. Nothing here sets the character between your CSV’s columns either, which is always found for you.

Step 7: Pick the fields to clear

Clean Fields only appears in Clean mode, and it is the list of fields your import will empty on every record it matches. You get a checkbox per field, grouped the same way the mapping screen groups them, with the same search box and filter chips pinned above. Check at least one or Next stays off.

Clearing the inventory pair on products leaves the product untracked with every stock number empty, so check those two together or not at all.

Some fields never appear on this screen, whatever you are looking for. Names and identifiers do not appear, because clearing what a record is found by would leave you no way to find it again. That covers SKU, Slug and a product’s Title. It also covers the name of a brand, a category, a tag or a definition, the text of a value, and an asset’s Display Name. The numbers the PIM maintains for you do not either, and those are Supplier Cost, On-hand Stock and Supplier Stock. Neither do the columns that always have something in them, such as the position and sort columns and every unit column.

Step 8: Check the summary and submit

Summary is a panel called Import Summary listing back everything you chose, so read it before you click anything.

The rules are written the way the PIM reads them. A single rule on SKU shows as sku, and a compound rule on barcode plus brand shows as gtin+brand_name. When every missing-reference answer is the same and there are two or more, they collapse into one row reading Skip with warning (all). Expect one oddity: a Tags import in Update shows an Update behavior row even though the Tags card never offered you the control.

Submit is in the bottom right and checks everything again, your match rules included, then starts the import without uploading your file a second time.

Limits

What an import cannot do

How a products file has to be shaped

A products file is the one with a shape of its own. A spreadsheet has one row per line of data, and a product with variants is more than one line of data. Get the shape wrong and every row of a product fails together.

One row per variant, grouped by slug

Every row of one product has the same Slug, and that is what tells the PIM the rows belong together. The first row of each group is the main product row: it has the Title and everything that describes the product as a whole. The rows after it are variant rows, and they can leave the product fields blank while giving their own option values.

• A product with a single variant and no options is one row, with everything on it.
• Anything else is one main row, then one row per variant. A product with 4 variants is 5 rows.

You need Slug on every row without exception, and it is never worked out from Title. A group with no main row fails, and so does a variant row with no option name cells, because neither one can be read as a variant of anything.

The simplest way to get the shape right is not to build it. Export the products first, edit the file you get, and send that back: an export already comes out in exactly this layout.

Option columns

An option is a variant axis, such as Color or Size. Each one is a pair of columns: Option 1 Name names the axis and Option 1 Value gives this row’s value on it, and Option 2 Name and Option 2 Value do the second axis, and so on.

You always get at least 3 pairs on the mapping screen, and more if your file has more, up to 50 pairs. Write the header as Option 1 Name, option_1_name or option1_name and all three are recognized. Every variant of one product has to list the same axes in the same order. No two variants can end up with the same combination of values.

Columns that come out of an export and cannot go back in

Most of a products export goes right back in, column names and all. These are the ones that do not.

Leaving them in your file is harmless. They arrive unmapped and are dropped, so there is no need to strip an export before sending it back.

When something goes wrong

Watching your import run

Your import appears in the table right away and moves through these statuses:

One import runs at a time and the rest queue behind it, first in first out, so several of yours can be waiting. The percentage is the only progress you get: no time estimate, no rows a second, and no live list of errors. Nothing about what went wrong comes to you until the import finishes.

There is no partial status. An import with at least one success ends as Completed even if half the file failed, and Failed means nothing at all went in. So read the four counters, never the status alone.

An interrupted import restarts on its own within 2 minutes and one that was downloading images continues where it stopped. An import still running after 4 hours is marked Failed for you.

Wherever you happen to be in the app, a small message pops up when your import finishes, whether it completed, failed or was canceled.

Canceling one

Cancel is a button at the end of the import’s row in the table. It works while the import is queued, pending, validating, processing or importing assets, and not once it gets to Finalizing. On a row where it cannot be used, hovering it tells you why.

Canceling keeps every row already written. New image downloads stop within 1 second, and downloads already in flight finish and leave their files in your asset library unattached to anything.

Reading the imports table

A counter showing zero reads as a dash. All four sort and filter, and hovering a counter’s heading tells you what it counts. The Entity, Mode and Status dropdowns above the table only list values your team has actually used, so a short list there is normal. If you find yourself building the same filters every week, saved views keeps them for you.

That is why fixing one real error often clears a dozen blocked rows at once. Warnings work the other way around. When a product saves and its main row collected warnings, every variant row is marked, so you open the main row.

Getting the Results file

Results is a button at the end of the import’s row in the table, next to Cancel. It turns on once the import finishes, and until then hovering it says so. Clicking it asks whether you want CSV or Excel, and then builds the file while you wait.

You get your original upload back with 2 columns added on the end, result and message, and one row out for every data row you sent in.

Sort or filter the result column, errors first and blocked second. Row 1 in the report is the first data row of your file, and the header is not counted. So the numbers line up with your spreadsheet once you allow for that. A message names the kind of problem and not the value that caused it, so use the row number to find the cell.

The file is named after yours, as catalog_results_2026-07-31.csv, using the date the import was created. It is rebuilt every time you ask for it, so you can come back for it as long as the import is still in the table, which is forever. Closing the dialog while it builds does not cancel it. If it takes longer than 2 minutes you are told to click Results again in a moment to pick it up.

The email you get

The email goes to whoever created the import and to no one else. You only get it when the import gets to Completed, so a failed or canceled one emails no one. There is no notification center in the app to check instead.

It has no attachment and no link to the Results file, so the table is still where you go for that. The email is on by default and you can turn it off under Import complete in your notification settings.

Errors before any row is read

These stop the file rather than a row, so nothing at all is written.

Paste a web address that returns a page instead of a file and you get That address returned a web page instead of a data file. The message goes on to name the fix for the two services this happens on most.

Some failures add a technical detail line under them, in a monospaced font below a dashed line. That line is for support, not for you.

The errors you will actually see

These are the ones that come up on ordinary files. The accordions below have the rest, grouped by what they are about.

Fixing a file and importing again

Download the Results file, fix your source file, and import again.

So either cut those rows out of the file, or switch the import to Update, which rewrites them and leaves everything you did not map alone. Update is usually the faster of the two, because you do not have to work out which rows made it.

Images downloaded before a product was rejected stay in your library. Your next attempt finds and reuses them, so retrying a products file does not fill your library with duplicates.

Where to go next