START WITH MEANING
A mapping rule needs evidence and a stop condition.
Keep an untouched source and a current export or template from the destination store. Record the source field, target field, transformation, and the buyer decision that makes it valid. A supplier cost, a parent code and a stock count are different facts.
This article uses invented data for a new-product example with Color and Size options. It does not cover an existing-catalog update. No customer data or real store import was used.
Shopify’s current specification uses headings such as URL handle, SKU and Price; older headings remain supported. Check the current Shopify CSV specification against the buyer’s template.
REPRODUCIBLE SYNTHETIC FILES
Six source rows. Four reviewed rows. Two explicit holds.
All CSV files are UTF-8 with comma-separated fields. Row numbers count the header as row 1. The source contains a comma and Chinese text in a quoted name. These small files have no multiline cells.
1. Untouched supplier source
Six rows, 11 supplier columns. Includes one cost-only amount and one missing product group. This is not a Shopify import file.
Download CSVsupplier-source.csv
2. Teaching target columns
Header only: 12 selected current Shopify columns. A small column specification, not the complete official template or a file to import.
Download CSVshopify-target-columns.csv
3. Held candidate — do not import
Six rows, 12 columns. Intentionally retains numeric faults, omits Color, and carries two unresolved business decisions.
Download CSVshopify-held-candidate.csv
4. Reviewed teaching candidate
Four rows, 12 columns. Uses only approved synthetic rules; two source rows remain on hold. Local clear does not establish store acceptance.
Download CSVshopify-reviewed-candidate.csv
Rules are explicit; approvals are synthetic.
The invented buyer confirms one TEE product, Color and Size options, USD selling prices, single-item stock and per-variant kilogram weights. Source rows 6 and 7 remain unapproved. These decisions are teaching inputs, not facts inferred by AI or by the scanner.
Download the complete demo rules and hold listFIELD-BY-FIELD DECISIONS
Use the source meaning to choose the destination.
| Source | Selected target | Rule and boundary |
|---|---|---|
group_code | URL handle | The invented buyer assigns TEE to dp-demo-tee. Keep one product group together. A blank group stays on hold; a parent code is not a variant SKU. |
supplier_sku | SKU | Preserve the confirmed variant identifier as text. Do not infer a parent, color or size from its spelling. |
name | Title | Use the confirmed product name on the first row of the group; preserve the comma and Chinese text with CSV quoting. |
color + size | Option1 name/value + Option2 name/value | Represent Color and Size as two options. Different SKUs with the same represented options still collide. |
amount + amount_kind + currency | Price | Only approved selling amounts in USD qualify in this demo. The cost-only amount 8.20 is held; there is no guessed margin or exchange rate. |
stock | Inventory quantity | Here the buyer defines single-item counts for a store with exactly one inventory location, including 6 pcs = 6. Tracking and fulfillment dependencies need separate review. |
weight + weight_unit | Weight value (grams) | The declared per-variant unit is kg: 0.20 × 1,000 = 200 grams. Never remove a unit without identifying it. |
Explicit demo rule | Status + Published on online store | Use draft and false in every teaching row. Actual store settings and publication controls still need buyer review. |
Shopify distinguishes the customer-facing price from cost per item, and store currency is a separate setting. A numeric value alone does not establish either meaning. Shopify product pricing reference.
WHY THE FIRST MAPPING FAILS
Dropping Color merges different variants.
Held mapping: only Size
Red S and Blue S both become dp-demo-tee + S. Red M and Blue M both become dp-demo-tee + M. Green S collides too. Different SKUs do not repair the missing option dimension.
Local result: six rows, 12 columns, blocked. There are two errors (INVALID_PRICE at row 2 and INVALID_INVENTORY at row 3), plus three DUPLICATE_VARIANT_KEY warnings at rows 4, 5 and 6.
Reviewed mapping: Color + Size
The first four source rows preserve Red/S, Red/M, Blue/S and Blue/M under one handle. Under the declared rules, $19.90 becomes 19.90, 6 pcs becomes 6, and 0.20 kg becomes 200 grams.
Local result: four rows, 12 columns, clear with zero findings. Each row uses draft and false. This result does not certify a Shopify import.
Shopify documents duplicate option combinations as an import problem. Our local warning name and severity describe Data Preflight’s check, not an actual Shopify error received for this file. Shopify import troubleshooting.
LOCAL CLEAR HAS A LIMIT
Keep the missing business decisions visible.
Source row 6: cost-only amount
DP-GREEN-S has amount_kind=cost and amount=8.20. That number passes a numeric price check. It is still not an approved selling price. Ask for the intended retail price and currency; keep this record on hold.
Source row 7: unknown product group
DP-BLACK-M has no group_code. The held target has a Title, so the local missing-identity rule does not fire. Its product relationship remains unknown. Ask whether to create a separate product, join a group, or update an existing product.
Account for every source row.
Four reviewed records plus two held records equal all six source records. The source retains both held rows. A clean-looking export must not silently lose them, invent a price, or infer a relationship from a SKU.
Inspect all five local findings and both human questions in the report sample
BUYER-CONTROLLED TEST IMPORT
Check the store context before using any candidate.
For a real job, the buyer must confirm product identity, create-versus-update intent, store currency, inventory locations and the agreed option model. This example omits images, metafields, taxes, shipping configuration, fulfillment services and Markets pricing. The local integer check does not validate inventory tracking, fulfillment dependencies, or whether quantities will be applied in the destination store.
Existing-product updates require a separate plan: matching handles and included blank columns can overwrite store values, and changing option values can replace variant IDs. Back up the catalog, inspect dependencies, and let the buyer test a small representative subset in a development store. Shopify’s import and overwrite guidance.
To reproduce our file-only result, download each candidate, choose Shopify in the free local scanner, and compare the row counts and codes above. No store connection is used. The header-only teaching specification is not a scanner test or an import file.