This guide explains the Import strategy step in the Simple CSV Shopify app.
When you upload a CSV, XLS, XLSX or XML file, Simple CSV asks how you want to import your products. This step decides whether you add new products or update existing ones and how rows in your file should be treated. Excel imports read the first worksheet only.
If your file matches a known format, Simple CSV usually selects the right options automatically. If your file is matched to Generic fields, you may need to review and adjust the settings yourself.
Install Simple CSV Shopify app
What the Import strategy step does
This step controls how new and existing products are handled. It also sets the way variant rows are grouped:
- Add new products or update products already in Shopify
- Whether each row in your source is a separate product or part of a multi-row product with variants
- How Simple CSV should identify or group rows when needed
Choosing the right settings here helps prevent skipped rows, wrong product grouping or updates to the wrong product.
Use a header row for mappings that survive column changes
When the first row contains headers, Simple CSV saves each mapped field against its column name. If a supplier adds, removes or reorders columns later, a Pro or Scale automation still finds the mapped data by header name.
Header matching is case-sensitive and ignores spaces at the start or end. If two columns have the same header, Simple CSV numbers them in order. Two columns named Price become Price and Price#2.
Some mappings still use column positions:
- A file set to First row is not a header
- A column with a blank header
- A column whose header contains
|or*
Changing the column order can break these positional mappings. Use a unique, non-blank header for every mapped column when you control the file.
If a mapped header is missing, Simple CSV stops that product and logs an error instead of sending incomplete data to Shopify.
Existing scheduled feeds move to header-based mappings cautiously. The first scheduled run records the current columns without changing the mapping. The next run upgrades only fields whose columns stayed in place. The import log shows Upgraded legacy positional mapping to column name for field: … for an upgraded field. If mapped columns moved between those runs, the mapping stays positional and the log shows Legacy positional mapping was not upgraded because mapped column positions changed. Review that automation’s mapping before its next run.
One-off imports do not need this upgrade because they are mapped and run in one pass.
For CSV files, the header is the first line that contains any data. Simple CSV skips blank lines above it instead of importing the real header as a product.
Choose between adding new products and updating existing products
The first choice is whether you want to create new products or change products that already exist in your Shopify store.
Add new products
Choose this option when your file contains products you want to create in Shopify.
This is the right choice if:
- You are importing these products for the first time
- You do not want to update products that already exist
When you choose this option, Simple CSV treats the file as a new product import.
Choose the status for all new products
The Preview page has a Status row that shows the status Simple CSV will write. If you want every new product to use the same status, open Override status for all new products and choose:
- Active
- Draft
- Unlisted
Unlisted products can be opened and bought through a direct link, but they stay out of Shopify-powered search, collections and recommendations.
The override replaces a mapped Status column and the default status. Choose Use mapped status (default: Active) to clear it and return to the mapped or default value. Archived is not an override option.
When an override is active, the Status row changes immediately. It also shows Overridden for all new products. Mapped value: X, so you can compare the override with the value from your file before saving.
This setting applies only to newly created products. It never changes an existing product during an update import. The override is available on every plan. When an import is saved as a Pro or Scale automation, the saved status choice is used whenever the scheduled file is processed.
Change products you already have
Choose this option when your file is meant to update products that already exist in Shopify.
This is the right choice if you want to update fields such as title, price, stock or description for products already in your store. A mapped barcode column updates the first barcode on each variant and leaves any other barcodes in place. To leave barcodes alone, remove the barcode column or do not map it.
To do this, Simple CSV needs a way to match each row in your file to an existing Shopify product or variant.
Important to know:
- If no matching product or variant is found, the row is skipped
- If an exact SKU or first barcode matches more than one product, the row is skipped rather than assigned to one of them
- It does not create a new product when a match is not found
The import log reports the identifier and number of matching products when it skips an ambiguous row. This makes the result deterministic and avoids updating the wrong product.
Choose how products are structured in your file
The next choice is about how your products are stored in the file.
Each row is a separate product
Choose this when every row in your file represents one complete product.
This is usually correct when:
- Your products do not have variants
- Each row stands on its own
- No product appears on multiple rows
Some products use multiple rows (variants)
Choose this when the same product appears on multiple rows, usually because it has variants such as size or color.
For example, one T-shirt may appear on several rows:
- One row for size S
- One row for size M
- One row for size L
In this case, Simple CSV needs to know which rows belong to the same product.
How Simple CSV combines rows for variant products
If you choose Some products use multiple rows (variants), you will also need to choose the column that contains the shared value.
This is the value that repeats across all rows for the same product.
Common examples include:
- Handle
- A product group ID
- Another column that stays the same for every variant of one product
Simple CSV groups rows using only the column you select here.
It does not automatically figure out variant groups from several columns at once.
That means the grouping column is very important.
If the grouping column is correct, all matching rows are combined into one product with variants.
If the grouping column is wrong or inconsistent:
- Rows that should stay separate may be merged into one product
- Rows that belong together may be split into separate products
- Blank values may cause rows to be treated as separate items
For most Shopify-style CSV files, Handle is usually the correct choice.
How Simple CSV matches existing products when updating
If you choose Change products you already have, you also need to tell Simple CSV how to find the correct product or variant in Shopify.
The most common matching options are:
- SKU
- Barcode / EAN / GTIN / ISBN
- Product handle
- Shopify Product GID
- Shopify Variant GID
Simple CSV compares SKU, handle and the first barcode exactly after ignoring letter case and surrounding spaces. This means blue-shirt, Blue-Shirt and Blue-Shirt match the same product. A value such as SF-2000-SET does not match SF-2000-SET-CP.
Shopify variants can have several barcodes, but Simple CSV checks only the first one. A secondary barcode in the file does not match. The row is skipped as not found, which can make a product look missing from an update or a Pro or Scale scheduled feed. Use SKU or a Shopify GID when you can.
If the exact SKU or first barcode appears on more than one product, Simple CSV does not guess. It skips the row and records the duplicate count in the import log. Matching by Shopify Product GID or Shopify Variant GID is unchanged.
Duplicates inside the update file follow a different rule. If the file repeats a SKU or first barcode, Simple CSV processes every row in file order. The last successful row for that identifier determines the final value. If an update uses handle as its match key, only the first row for that handle is processed. Later rows with the same handle have no effect, do not add to the skipped-row count and do not produce a warning in the import log.
This handle rule only applies to update matching. It does not affect new-product imports that group several variant rows under a shared handle.
This is the same for CSV, XLS, XLSX and XML uploads, URL imports and published Google Sheets. Check the file itself for repeated identifiers when an update reports success but a later row did not take effect.
Best options for most stores
For most merchants, the best choices are:
- SKU if each product or variant has a unique SKU
- Barcode / EAN / GTIN / ISBN if each variant has one reliable barcode
- Product handle for product-level updates when your handles are correct and unique
Important limitation when matching by handle
If you match by Product handle, Simple CSV updates product-level data only.
It does not update variant-level data in that case.
The same applies to Shopify Product GID. These are product-level identifiers.
If you need exact variant-level updates, use:
- SKU
- Barcode
- Shopify Variant GID
Advanced matching options
Shopify Product GID and Shopify Variant GID are mainly for advanced users, app exports or API-generated files.
They are useful when your file already contains Shopify IDs and you want very exact matching.
For normal manual spreadsheets, SKU is usually the best choice. A first barcode also works when each variant has only one barcode. A handle works for product-level updates.
Check the record selection for an XML file
XML files use the same field-mapping step as CSV and Excel files. The mapping screen shows an XML records section with the selected part of the feed and the number of records found.
If the section offers more than one option, choose the part that contains the products you want to import from the Record element dropdown, then select Use this record element. Changing it refreshes the preview and clears the current mapping. You do not need to upload the file again.
XML files with a DOCTYPE declaration are rejected. A single record cannot be larger than 10 MB. A file without a repeating element containing fields fails with No repeating XML record element containing fields could be detected. Invalid XML shows the parser error returned for the file.
When you usually do not need to change anything
If Simple CSV recognizes your file format, it often pre-selects the correct settings for you.
For example, if you upload a Shopify-format CSV or another known format, the app may already choose the correct structure and grouping options.
In that case, you usually do not need to change anything unless the detection looks wrong.
If the message says your file was matched to Generic fields, review each option more carefully before continuing.
Best practices for this step
- Choose Add new products when importing products for the first time
- Choose Change products you already have only when your file contains a reliable identifier for matching
- Use Each row is a separate product when products do not span multiple rows
- Use Some products use multiple rows only when variants are spread across several rows
- Use a grouping column that stays exactly the same for all rows of the same product
- Prefer SKU or Shopify Variant GID for variant-level updates
- Check the import log for identifiers that match more than one product
- Use a unique, non-blank header for every mapped column in a saved feed
Common mistakes to avoid
- Choosing update mode when your file is actually meant to create new products
- Reusing one SKU or first barcode across products, which causes ambiguous rows to be skipped
- Using handle when you expect variant-level updates
- Choosing the wrong grouping column for multi-row products
- Reordering columns in a headerless file, which still uses column positions
- Changing auto-detected settings even though the file was correctly recognized
What to choose if you are not sure
If you are unsure, start with these simple rules:
- If the products do not exist in Shopify yet, choose Add new products
- If every row is one product, choose Each row is a separate product
- If one product appears on several rows because of variants, choose Some products use multiple rows and select the repeated shared column, usually Handle
- If you want to update existing products, use the most reliable unique identifier in your file, usually SKU
If your file was matched to Shopify fields automatically, the safest option is usually to leave the detected settings as they are.
If you are choosing an import strategy for a recurring supplier feed, read our Shopify supplier sync guide. Scheduled URL imports are available on Pro and Scale.