Product Recall Catalog Monitor

What does Product Recall Catalog Monitor do?

Product Recall Catalog Monitor checks a user-provided product catalog against official CPSC Recalls API records and official EU Safety Gate alerts. It is not a raw recall feed exporter; it turns official Recall Notices into SKU-level Match Results with Confidence Scores, Match Evidence, official URLs, images when available, and a Markdown review report.

This Actor uses official source systems only. EU Safety Gate records are loaded from European Commission Safety Gate endpoints, not from derived public mirrors.

Why use Product Recall Catalog Monitor?

E-commerce operators, marketplace sellers, importers, distributors, product safety consultants, and compliance teams often need to know whether their own catalog contains products that may require recall review. Manually searching recall pages SKU by SKU does not scale.

This Actor helps by:

• Loading catalogs from pasted CSV, public CSV URL, pasted JSON, or an Apify Dataset ID.
• Mapping user columns into canonical catalog fields such as SKU, product name, brand, model, GTIN/EAN/UPC, category, supplier, manufacturer, lot, batch, and product URL.
• Validating rows before matching and preserving invalid catalog feedback separately from Match Results.
• Fetching CPSC recalls and EU Safety Gate alerts for a configured inclusive date range.
• Generating indexed candidates by identifier, model, brand, rare product tokens, category, and supplier/manufacturer signals.
• Scoring matches by exact identifiers, model, brand, product name similarity, category, market, supplier/manufacturer, and lot/batch evidence where available.
• Producing Confidence Scores, Confidence Bands, score breakdowns, signal details, Match Evidence, and recommended human-review actions.
• Writing a Markdown report that can be reviewed by operations or compliance teams.

Because this runs on Apify, you can schedule it, call it through the Apify API, use webhooks, and download output datasets as JSON, CSV, Excel, HTML, RSS, or XML from the Apify platform.

What data can Product Recall Catalog Monitor output?

Output	Type	Description
Match Results dataset	Dataset rows	Flat SKU-level possible matches with catalog fields, recall fields, Confidence Score, evidence, official URL, human-review flag, and optional incremental deltaStatus.
OUTPUT	JSON	Run Summary with selected sources, Source Status entries, catalog counts, source record count, match total, Billing Summary, and incremental delta fields when enabled.
REPORT.md	Markdown	Human-readable summary with immediate review, possible matches, source status, incremental delta sections when enabled, and disclaimer sections.
SOURCE_STATUS.json	JSON	Per-source success, error, or spending-limit skip status for CPSC and EU Safety Gate.
MATCHING_STATS.json	JSON	Matching counts by confidence band, source, returned status, and selected matching controls.
INVALID_ROWS.csv	CSV	Invalid Catalog Rows excluded from matching, such as rows missing product name.
CATALOG_QUALITY.json	JSON	Catalog Quality Warnings such as missing recommended fields, invalid identifiers, duplicates, or truncation.
RAW_SOURCE_RECORDS.json	JSON	Optional normalized Recall Notices with raw source fields, written only when includeRawSourceRecords is enabled.

How to scan a catalog against CPSC and EU Safety Gate notices

1. Choose one catalog input mode: public CSV URL, pasted CSV text, pasted JSON text, or Apify Dataset ID.
2. Map your catalog columns in the fieldMapping object. At minimum, map SKU and product name. Brand, model, GTIN/EAN/UPC, and category improve match quality.
3. Set sources to ["cpsc"], ["eu_safety_gate"], or both.
4. Choose dateMode. Use last_days for the default rolling range, or custom_range with fromDate and toDate.
5. Set maxSourceRecords if you need a deterministic per-source cap on normalized Recall Notices.
6. Run the Actor and review the default dataset plus REPORT.md.
7. Verify any Match Result against the official source URL before taking business, legal, product safety, or compliance action.

How much will it cost to scan official recall sources?

This Actor uses pay-per-event billing hooks. In local or non-PPE beta runs, the Actor simulates the same events and writes them to OUTPUT.billingSummary; in Apify PPE runs, custom events are charged through Actor.charge().

Beta pricing:

Event	When it is counted	Price
apify-actor-start	Actor run start, handled by Apify's synthetic start event	Store configuration
catalog-product-row	Each processed catalog row, including Invalid Catalog Rows and excluding truncated rows	$0.75 / 1,000 rows
recall-notice-checked	Each Recall Notice actually fetched and used	$0.20 / 1,000 notices
report-generated	Full Markdown report generation	$0.50

Example estimate: a run that processes 5,000 catalog rows, fetches 700 Recall Notices, and generates one report would cost $3.75 + $0.14 + $0.50 = $4.39, plus the configured Apify Actor start event.

If the configured spending limit is reached, the Actor performs a Spending Limit Stop. It writes a clear OUTPUT, Source Status entries, any dataset rows already produced, and a minimal REPORT.md explaining the stop instead of continuing into more chargeable work.

Input

See the Actor input tab for the full configuration. The most important fields are:

• catalogInputMode: exactly one of public_csv_url, csv_text, json_text, or apify_dataset.
• fieldMapping: maps user column names into canonical catalog fields.
• sources: one or both of cpsc and eu_safety_gate.
• dateMode, lastDays, fromDate, toDate: controls the inclusive source date range.
• maxCatalogRows: caps catalog processing and emits a Catalog Quality Warning when truncated.
• maxSourceRecords: caps normalized Recall Notices per source after dedupe and deterministic date ordering.
• matchingMode: choose strict, balanced, broad, or debug. Strict is conservative, balanced is the default, broad supports lower-confidence review when combined with lower thresholds, and debug includes discarded candidates for troubleshooting.
• minConfidence: default 65, which includes medium, high, and very_high Confidence Bands.
• includeLowConfidenceMatches: includes low-confidence Match Results when enabled.
• includeRawSourceRecords: writes RAW_SOURCE_RECORDS.json with normalized Recall Notices and their source raw fields. Raw source records are not added to the Match Results dataset.
• incrementalMode: uses a named Key-Value Store to classify current Match Results as new or previously_seen across scheduled runs.
• stateStoreName: required when incrementalMode is enabled; choose a stable name per scheduled monitoring setup.
• reportFormat: markdown in the beta Actor.
• debugMode: writes diagnostic artifacts such as MATCHING_STATS.json. To include discarded candidates in the dataset, set matchingMode to debug.

Output

The default dataset is designed for review in Apify Output. Each Match Result is flattened so the most useful fields are visible as table columns.

When incrementalMode is enabled, each dataset row includes deltaStatus. OUTPUT and REPORT.md also include newMatches, previouslySeenMatches, lastSuccessfulRunAt, catalogFingerprintChanged, and a deltaSummary. Incremental mode is source-notice centric: a Recall Notice is considered previously seen by source and sourceRecordId, even if a changed catalog makes it match a new or changed Catalog Item.

Example dataset row with incrementalMode enabled:

{
  "confidenceScore": 95,
  "confidenceBand": "very_high",
  "matchStatus": "possible_match",
  "deltaStatus": "new",
  "sku": "A-1",
  "productName": "Acme Wooden Train",
  "model": "WT-200",
  "gtin": "012345678905",
  "source": "cpsc",
  "jurisdiction": "US",
  "sourceRecordId": "26-123",
  "recallTitle": "Acme Recalls Wooden Toy Trains Due to Choking Hazard",
  "officialUrl": "https://www.cpsc.gov/Recalls/2026/acme-recalls-wooden-toy-trains",
  "imageUrls": [],
  "identifierMatch": true,
  "matchedFields": ["identifier", "model", "category"],
  "scoreBreakdown": [
    {
      "signal": "identifier_exact",
      "points": 70,
      "details": "Catalog identifier matches recall identifier."
    }
  ],
  "signalDetails": {
    "candidateReasons": ["identifier", "model", "category"],
    "scoringVersion": "explainable-v1"
  },
  "requiresHumanReview": true
}

Demo catalogs and expected outputs

The release demo matrix is documented in examples/release-demo-matrix.md, with structured expected outcomes in examples/release-demo-matrix.json.

The matrix covers exact identifier matching, name-based review matching, a no-match control, Incremental Monitoring State / Delta Summary behavior, and Spending Limit Stop behavior. Each demo defines the expected Match Result shape, Confidence Band, Human Review Flag, Run Summary, Billing Summary, source fixtures, and verification command. The demos remain limited to CPSC and EU Safety Gate and do not imply openFDA, USDA FSIS, food, pharma, medical-device, or global recall coverage.

The original beta catalog demos are also available in examples/:

Demo	Catalog	Input file	Expected-output examples
Toy catalog	examples/toy_catalog_demo.csv	examples/demo_toy_catalog_input.json	examples/expected-output/toy_catalog/
Mixed ecommerce catalog	examples/mixed_ecommerce_catalog_demo.csv	examples/demo_mixed_ecommerce_input.json	examples/expected-output/mixed_ecommerce/

Run a catalog demo locally without editing source code. For deterministic fixture-backed release demo runs, set the fixture environment variables shown in examples/release-demo-matrix.md first.

apify run --purge --entrypoint src/main.py --input-file examples/demo_toy_catalog_input.json
apify run --purge --entrypoint src/main.py --input-file examples/demo_mixed_ecommerce_input.json
apify run --purge --entrypoint src/main.py --input-file examples/demo_name_review_input.json
apify run --purge --entrypoint src/main.py --input-file examples/demo_no_match_control_input.json

Verify the complete release matrix:

$uv run --locked pytest tests/test_release_demo_matrix.py

In Apify Console, paste the corresponding input JSON or use the catalog CSV values from the demo catalog files. The expected-output examples and release matrix show representative OUTPUT, MATCHING_STATS.json, dataset item, Billing Summary, Delta Summary, and REPORT.md shape for beta review.

Store listing and onboarding package

The Apify Store launch package is split into three repository docs:

• docs/apify-store-listing.md: Store title, short description, long description, keywords, categories, use cases, pricing, limitations, and support copy.
• docs/apify-store-onboarding.md: first-run onboarding flow aligned with the current input schema, output schema, dataset schema, and Key-Value Store artifacts.
• docs/apify-store-assets.md: sample-output and screenshot source list traced to verified release evidence under docs/release-evidence/2026-07-06-beta/.

Beta learning and launch gates

The internal beta learning plan and publish/hold launch gate criteria are documented in docs/beta-learning-plan.md. Use that plan to decide whether the current CPSC and EU Safety Gate scope has enough evidence to publish or whether the release should hold before any v1.1 source expansion.

The beta measurement cadence and feedback intake path are documented in docs/beta-measurement-and-feedback.md. Use the GitHub beta feedback issue template for false positives, false negatives, requested sources, pricing confusion, and source reliability complaints.

Tips and advanced options

Confidence Bands are very_high, high, medium, low, and discard. Exact UPC/EAN/GTIN matches score very high by default unless strong contradictory evidence is present. Name-only matches are conservative, and generic name-only matches without brand, model, or identifier evidence cannot exceed low confidence. Invalid Catalog Rows and Catalog Quality Warnings are not mixed into the Match Results dataset; they are written to key-value store artifacts so the dataset stays reserved for possible recall matches.

FAQ, disclaimers, and support

Does this Actor confirm that a product is recalled?

No. A Match Result is an automated possible match that requires human review. Always verify the official CPSC or EU Safety Gate notice before taking action.

Does EU Safety Gate use a fallback mirror?

No. This Actor intentionally uses official EU Safety Gate endpoints only. If the official source fails or changes shape, the run records an EU Safety Gate Source Status error and continues with other selected sources.

Is this legal, medical, food safety, regulatory, or compliance advice?

No. This Actor is an automated monitoring aid. False positives and false negatives are possible. It does not provide legal, medical, food safety, regulatory, or compliance advice.

Where should issues or feature requests go?

Use the repository issue tracker for feedback and follow-up work. During beta, use the beta feedback issue template so reports include the run ID, source, source record ID, Match Result ID when available, observed behavior, expected behavior, and supporting Actor output fields.

Development

Required tools:

• Python 3.14
• uv
• just
• apify-cli

Common commands:

just bootstrap
just check
just actor-validate
just actor-run