Shopify Variant & Option Mapper CSV

Turn a public Shopify store's product feed into one flat, normalized row per variant, with size and color columns and a list of variant integrity problems. It is built for catalog cleanup, SKU mapping between systems, and pre-migration audits.

What it does

For every variant it outputs:

• Product and variant identifiers, SKU, barcode, price, compare-at price, availability.
• Up to three option name/value pairs (option1_name, option1_value, ...).
• size_value and color_value picked from options whose names contain "size", "color" or "colour".
• option_combo_key, a lowercase key such as size=s|color=red, for joining against other systems.
• Product-level grid statistics: variant count, expected option combinations, missing combinations.
• issues, a semicolon-separated list of detected problems, plus issue_count and has_issues.

Integrity checks

Issue	Meaning
MISSING_SKU	Variant has an empty SKU.
DUPLICATE_SKU_IN_PRODUCT	Same SKU (case-insensitive) used by several variants of one product.
DUPLICATE_SKU_IN_STORE	SKU already seen on an earlier product in this run (later occurrences are flagged).
DUPLICATE_BARCODE_IN_STORE	Barcode already seen earlier in this run.
MISSING_OPTION_VALUE	One of the product's options is empty for this variant.
DUPLICATE_OPTION_COMBINATION	Two variants share the same option combination.
OPTION_VALUE_SPELLING_VARIANT	Values differ only by case or whitespace (for example Red and red ).
MISSING_OR_ZERO_PRICE	Price is empty, not numeric, or zero.
COMPARE_AT_BELOW_PRICE	Compare-at price is lower than the price.

Sample input

{
    "storeUrls": ["https://www.allbirds.com"],
    "maxProductsPerStore": 50,
    "onlyRowsWithIssues": false,
    "requestDelayMs": 1000
}

Replace the sample store with stores you are allowed to analyze. To work without any network request, paste an existing products.json into inlineProductsJson.

Field	Description
storeUrls	Up to 10 public HTTPS store URLs. Only the domain is used.
maxProductsPerStore	1-2000, default 50.
collectionHandle	Optional single public collection, for example mens-shoes.
onlyRowsWithIssues	Output only variants with at least one issue.
requestDelayMs	500-5000 ms between requests, default 1000.
inlineProductsJson	Optional pasted feed text; disables network access.

Output

• Dataset: one item per variant (views: "Variant map" and "Integrity checks").
• Key-value store VARIANT_MAP_CSV: the same rows as a CSV file.
• Key-value store SUMMARY: per-store status, issue counts, rejected URLs and caveats.

Safety and politeness

• Only HTTPS domain names are accepted: no IP addresses, custom ports, credentials or local-looking hosts.
• Resolved addresses must be publicly routable; redirects are followed only within the same site and path.
• robots.txt is read first; if it disallows the feed or cannot be read reliably, the store is skipped.
• Requests are sequential, paced, and responses are size-capped. No proxies, logins or personal data are used.

Limitations and sample-size caveats

• Only the public products.json feed is used. Stores may disable, cache, paginate or trim it; hidden or draft products are not visible.
• Missing-combination counts compare the option grid visible in the feed. A "missing" combination may be intentional.
• Duplicate checks only see products read in this run, and flag later occurrences only. A small maxProductsPerStore can miss duplicates and gives a poor picture of the whole catalog.
• Stores that redirect to a different domain are reported as errors rather than followed.
• Size and color detection relies on option names; unusual or non-English names appear only in the raw option columns.
• DNS is checked before each request, but a determined DNS-rebinding race cannot be fully excluded.
• available can be empty when the feed does not expose it.

Billing

The code references one pay-per-event name, mapped-product, charged once per product that produced output rows. Failed stores, failed pages and invalid input are never charged. No payable plan or price is configured in this project.

Local tests

The unit tests run offline with the standard library: python -m unittest discover -s tests -t .