Shopify Store Catalog Diff Reporter

Compare two snapshots of a Shopify catalog and get a structured change report: added and removed products and variants, vendor changes, price and compare-at price moves, SKU, title, tag, handle and availability changes, plus per-vendor product count shifts.

Unlike a product scraper, this Actor is about differences between two points in time. You can paste snapshots you already hold (for example saved products.json files from earlier runs of any tool), so the default workflow makes no network requests at all.

Who it is for

• Ecommerce analysts and agencies tracking a store or competitor's public assortment between two dates.
• Merchants auditing a migration or bulk edit by comparing the catalog before and after.
• Teams that already collect catalog data and need a repeatable delta report.

Input

Field	Description
beforeSnapshot / afterSnapshot	Shopify products.json format: {"products": [...]}. Inline snapshots take priority.
beforeSnapshotUrl / afterSnapshotUrl	Optional public https:// feed URLs, used only when the inline snapshot for that side is empty.
matchBy	id (default) or handle.
includeVariantChanges	Report variant-level changes (default true).
minPriceChangePercent	Hide price moves smaller than this percentage (default 0).
maxChanges	Cap on emitted change rows (default 5000). The summary always counts everything.
maxFeedPages	Pages of 250 products per URL (default 4, max 20).

The prefilled input is a small copyable example: two tiny snapshots containing a vendor rename, a price rise, a new variant, a new tag, one removed product and one added product.

Minimal example

{
  "beforeSnapshot": {"products": [{"id": 1, "handle": "mug", "title": "Mug", "vendor": "Acme",
    "variants": [{"id": 10, "sku": "M1", "title": "Default", "price": "10.00", "available": true}]}]},
  "afterSnapshot": {"products": [{"id": 1, "handle": "mug", "title": "Mug", "vendor": "Acme Home",
    "variants": [{"id": 10, "sku": "M1", "title": "Default", "price": "12.00", "available": true}]}]}
}

Output

The dataset contains one summary record first, followed by change records.

• summary: product and variant counts before/after, changeCounts by type, vendorProductCountChanges, skipped/duplicate record counts, source details and caveats.
• change: changeType (product_added, product_removed, variant_added, variant_removed, vendor_changed, title_changed, product_type_changed, handle_changed, published_at_changed, tags_changed, sku_changed, variant_title_changed, price_changed, compare_at_price_changed, availability_changed), product and variant identifiers, before/after values and, for prices, priceDelta and priceDeltaPercent.

Public feed mode (optional)

When you supply a URL, the Actor only accepts https:// hosts with a public domain name whose /products.json path resolves to public IP addresses. It does not follow redirects, reads robots.txt first (and stops if it cannot be read or disallows the feed), limits page count and response size, and waits between pages. Only publicly visible feed data is read.

Limitations and caveats

• Public products.json feeds do not expose inventory quantities, draft or hidden products, costs, or customer data. Only public fields are compared.
• A diff covers two moments only; changes made and reverted in between are invisible.
• Some stores disable or customize /products.json; those cannot be fetched by URL. Paste a snapshot instead.
• With maxFeedPages reached, only the first products are compared and the report says so. Differences in feed ordering between fetches can create false added/removed rows on large catalogs.
• availability_changed relies on the available flag, which stores may omit.
• Snapshots with fewer than 30 products are flagged as small samples; treat counts there as anecdotal.
• Matching by id treats a re-created product (new id) as one removal plus one addition. Use matchBy: handle for such migrations.
• DNS is checked before the request, but the HTTP client resolves again, so the guard is best-effort against DNS rebinding.
• Not tested against real stores in this repository's offline tests; verify on your own feeds before relying on results.

Pricing

The code emits a single catalog-diff-report event once per successfully completed run, after results are stored. Failed runs (invalid input, rejected URL, robots denial, fetch errors) never reach that step. No payable plan is configured in this repository; any pricing is set separately on the platform.

Local tests

Tests are offline unit tests: python -m unittest discover -s tests -t .