# CSV Mapper — downloadable source and reference samples

**Every record in this pack is fictional. These are practice inputs for CSV Mapper, not ready-to-import Shopify, WooCommerce, customer, or promotion templates. Do not send messages to the example customers or use the example identifiers, approvals, stock, agreements, or policy limits as real business evidence.**

The app can read CSV, TSV, and XLSX files in the browser, map their columns, check the resulting records, and prepare supported export files. It does not write to a store or activate a promotion. Upload a sample to the app, review its mapping and findings, and download a separate prepared file. Neither the app nor editing a downloaded copy changes the original sample file.

## Choose an example

Counts below exclude the header row. Every CSV has its header in row 1 and its first record in row 2.

| File | Rows | Columns | What it demonstrates |
| --- | ---: | ---: | --- |
| [clean-products-source.csv](clean-products-source.csv) | 8 | 17 | Six explicitly related size options and two other products; numeric-looking SKUs remain text in the source. This is a flat source example, not a WooCommerce variable-product definition. |
| [variable-products-source.csv](variable-products-source.csv) | 4 | 21 | One variable parent and three linked sellable variations, with explicit Parent SKU and Size options. Use this for a WooCommerce parent/variation workflow. |
| [same-name-conflicts-source.csv](same-name-conflicts-source.csv) | 3 | 17 | The same title appears with different suppliers and categories. A name does not authorize merging the records. |
| [price-outliers-source.csv](price-outliers-source.csv) | 6 | 17 | Comparable sibling prices include deliberately unusual USD 300 and USD 3 values on source rows 6 and 7. |
| [missing-identity-fields-source.csv](missing-identity-fields-source.csv) | 4 | 17 | A missing name, price, and category; an explicit zero price; duplicate SKU; and reused fictional GTIN. |
| [categories-clean.csv](categories-clean.csv) | 3 | 4 | A Home → Kitchen → Mugs hierarchy using explicit parent slugs. |
| [categories-errors.csv](categories-errors.csv) | 6 | 4 | Missing name, duplicate slug, ambiguous/cyclic parent relationships, a spelling candidate, and a missing external parent. Resolve ambiguity before expecting a cycle check to identify a unique graph. |
| [customers-clean.csv](customers-clean.csv) | 2 | 11 | Fictional customer contact/address records with explicit No marketing consent. |
| [customers-errors.csv](customers-errors.csv) | 4 | 11 | Conflicting records under one email, malformed contact values, incomplete address, and unsupported/unknown consent. City/state correctness still needs human review. |
| [deals-clean.csv](deals-clean.csv) | 1 | 45 | A consistent single-SKU 20% offer with separate source values and evidence references. Reference-dependent checks need the reference workbook below. |
| [deals-errors.csv](deals-errors.csv) | 4 | 45 | Incorrect offer totals, missing costs/context, conflicting supplier facts, overlapping offers, unknown references, and BOGO fulfillment problems. |
| [csv-mapper-source-samples.xlsx](csv-mapper-source-samples.xlsx) | 21 product records | 17 per product tab | The same four flat product scenarios as the corresponding CSVs, plus three teaching tabs. |
| [deal-reference-example.xlsx](deal-reference-example.xlsx) | 11 reference records | Varies by tab | Eight separate reference tables for the deal checks. These are invented evidence fixtures, not store import files. |

The pack contains **11 CSV files and 2 XLSX files**. The CSVs contain 45 records in total across their separate scenarios. The 21 product records in the first workbook repeat its four matching CSV scenarios; they are not 21 additional products to combine with them. The linked-variation, category, customer, and deal CSVs are not included in that product workbook.

Keep scenarios separate. Combining them changes duplicate detection, available price peers, and promotion overlaps.

## Use the files in the app

1. Choose the correct sheet type: Products, Categories, Customers, or Deals.
2. Select the intended destination and read its setup note. For the flat sibling product examples, Shopify/Matrixify can interpret supported explicit option families. Native WooCommerce needs an explicit variable parent and child links; use the linked-variation example, or deliberately mark genuinely separate products as simple.
3. Upload the CSV or workbook. For the product workbook, select one of its four product tabs with header row 1, not a README, dictionary, or warning-reference tab.
4. Confirm source number conventions and currency. The product and deal examples use USD. For real product exports, the actual store currency must also be confirmed; the app does not convert currencies.
5. Review column matches and findings. Choose or supply confirmed values where needed. Preserve existing identities and correct source errors with evidence.
6. Inspect the prepared output and omission notes. Native headers, plugin mapping sheets, and promotion planning sheets serve different purposes.

The category hierarchy is suitable for practicing a mapped WooCommerce category workflow, such as WP All Import with the correct taxonomy import type. Shopify categories in this app mean Matrixify **Custom Collections**, which are flat collections: the sample hierarchy cannot become a collection parent tree or new Shopify taxonomy entries automatically.

Customer examples are creation inputs. Native Shopify customer overwrite can replace existing customer data; selective updates require the supported alternative and actual target identifiers. The sample's No/Yes/blank consent values are only fictional assertions.

## Product fields

The four flat product CSVs and all four product tabs have these **17 columns in this exact order**:

    source_record_id, product_name, supplier, category, brand, sku, price, currency,
    pack_quantity, tax_basis, condition, price_basis, gtin, variant_family,
    variant_option, sample_notice, variant_option_name

| Source field | Meaning and handling |
| --- | --- |
| source_record_id | Fictional source-row identifier. Leave it as source context; it is not a store product ID. |
| product_name | Supplied product title. A shared title does not establish identity. |
| supplier | Source supplier, distinct from manufacturer brand. |
| category | Source/WooCommerce classification. It is not automatically a Shopify or Google taxonomy value. |
| brand | Supplied brand. Unknown brand is not an assumed price-comparison match. |
| sku | Text identifier. Preserve leading zeros and verify the destination's matching scope. |
| price | Regular selling price in the stated currency and unit/pack context. Blank is unknown; zero is an explicit value. It is not cost or an active sale price. |
| currency | Explicit source currency code. Confirm the actual store currency separately; no exchange rate is applied. |
| pack_quantity | Supplied count used to compare like packs. It is not automatically multiplied, divided, or defaulted to one. |
| tax_basis | Supplied inclusive/exclusive price context. The app does not calculate tax. |
| condition | Supplied condition. These fixtures explicitly use new; the app must not infer it for other data. |
| price_basis | Meaning of the amount; these fixtures use regular. Keep selling prices, sale prices, and costs distinct. |
| gtin | Text barcode, if supplied. A valid check digit does not establish ownership or product assignment. |
| variant_family | Explicit source family. It is not an existing store ID or a substitute for WooCommerce Parent SKU. |
| variant_option | First option value, such as a supplied size. |
| sample_notice | Fictional-data label. Never map it into a product field. |
| variant_option_name | First option name, such as Size. It must accompany a supplied option value. |

The linked-variation CSV instead has **21 columns**. It adds explicit product structure, parent links, regular/sale price separation, cost, Shopify taxonomy, full option labels, and stock:

    product_name, sku, product_type, parent_sku, price, sale_price, cost, category,
    shopify_category, brand, supplier, currency, pack_quantity, tax_basis, condition,
    price_basis, variant_family, option1_name, option1_value, stock, sample_notice

Its variable parent has no sellable price. Each child has its own price, cost, and stock. Parent values must not become every child's values by assumption. WooCommerce category/tag membership belongs on the parent; child category cells can therefore produce omission warnings. The supplied Shopify full category path is a separate target field from the source label T-shirts.

## Category, customer, and deal fields

Category CSV headers are **Category name, Parent category, Category slug, Category description**. A parent slug defines an intended relationship; it does not prove that the parent exists in a live store.

Customer CSV headers are **First name, Last name, Email, Phone, Address 1, City, State, Country, Postal code, Marketing consent, Note**. Contacts and addresses are fictional. The app checks supplied syntax and conflicts; it does not verify mailbox delivery, phone ownership, postal deliverability, or city/state membership.

Both deal CSVs use the same **45 canonical source headers**, recorded exactly in manifest.json. Distinguish:

- **price**: regular price per unit.
- **units**: all items received in the complete offer, including free/discounted get items.
- **offerRegularPrice**: optional submitted regular total for the complete offer.
- **promoPrice**: submitted ending total for the complete offer.
- **discountValue**: 20 means 20% for a percent rule; an amount-off rule discounts the complete offer.
- **buyQuantity**, **getQuantity**, and **getDiscountPercent**: explicit BOGO/buy-X-get-Y mechanics where applicable.
- **cost**, **feeRate**, **fixedFee**, **otherCosts**: supplied costs and fees, not assumed zero.
- **marginFloor**: supplied contribution-margin floor, not a universal business rule.
- Dates, store/channel scope, agreements, policies, readiness flags, and approval references: evidence-dependent assertions, not proof of readiness.

The clean deal's regular offer is USD 30 and its expected promotional total is USD 24. That illustrates the arithmetic; it is not a live promotion. Sample dates are fixed. Expiration and timing findings can change with the review date or supplied business policies.

## Deal reference workbook

Upload deal-reference-example.xlsx as the optional **reference**, not as the main deal sheet. Keep these exact sheet names and headers:

| Sheet | Records | Exact headers |
| --- | ---: | --- |
| Products | 1 | sku, name, category, brand, supplier, price, cost, currency, stock, weeklyVelocity |
| Stores | 3 | code, active |
| Channels | 2 | code, active |
| Agreements | 1 | agreementId, brand, supplier, active, validFrom, validTo, maximumDiscountPercent |
| CategoryPolicies | 1 | category, maximumDiscountPercent, minimumGrossMarginPercent |
| Approvals | 1 | reference, approved, dealId |
| ChannelSnapshots | 1 | sku, dealId, channel, currency, promoPrice, startDate, endDate |
| ComplianceRules | 1 | id, type, value, severity, active |

Reference IDs and scope must match the intended record. MAIN, MAIN10, and MAIN1 are different store codes; a partial-name match is not accepted. Blank evidence does not pass a check. A policy, approval, agreement, or stock record in this workbook is fictional even if its active/approved cell says Yes.

These examples do not model mixed-SKU bundle costing, live inventory reservations, customer eligibility at checkout, a complete tax calculation, or legal compliance.

## Preserve identifiers and spreadsheet safety

All CSVs in this pack are UTF-8 with BOM, comma-delimited, and use CRLF line endings. Standard double-quote escaping is used where needed. **CSV cannot store cell types.** Import identifier columns as Text in your spreadsheet program. Quoting a numeric-looking value does not guarantee preservation when a CSV is opened directly.

The product XLSX stores source IDs, SKUs, GTINs, family IDs, and option values as text; its prices and pack counts use numeric cells, with missing prices left blank. The clean example includes SKUs **000250** and **000300**. The fictional GTINs **0000000000017** and **0000000000024** demonstrate check-digit and reuse checks only. Never copy them into a real catalog or invent replacements for blank GTINs.

The two inspected workbooks have no formula cells, macros, embedded files, or external workbook relationships. This is a file-structure observation, not a general guarantee about files you upload later. The app never executes source formulas; unsafe output text cannot be made safe merely by acknowledging a warning. Keep edited-source XLSX and review reports private, especially with real customer data.

## Google values and importer scope

There is **no separate Google feed** in this pack or destination list. Google product values belong in supported cells within the selected product export, after the actual installed integration and its mapping are confirmed. Source category text alone is not a verified Google or Shopify assignment.

Plugin mapper profiles need configuration inside the plugin. Native product CSV importers are not standalone customer/category importers. Promotion outputs remain planning sheets that require manual setup in the selected discount system.

## Results and verification

Expect more than the deliberate demonstration findings. Missing target taxonomy, unmapped teaching columns, unknown external evidence, variant structure, and plugin setup can all add findings. “Clean” means the main fixture values are intentional; it does not mean universally import-ready or independently verified.

The product workbook's teaching tabs describe the current upload and review workflow and define all 17 source fields. Expected_Warnings contains ten clearly labeled illustrative findings, not an exhaustive current total, live validator, or passing test report. Run the app's current checks after mapping and selecting a destination; its findings can extend beyond those examples.

manifest.json records the observed file sizes, SHA-256 hashes, row/column counts, ordered headers, and workbook structure. File inspection and module checks do not certify a browser release or a store import. Use the release QA record for completed test runs and remaining checks; test a small draft batch and re-export it before using real catalog data.