Product Variant Match Audit

Check product pairs before merging catalogs or comparing competitor prices. Get a field-by-field audit, explicit conflict reasons, and optional TypeSafe JEV recommendations: same, different, or review.

What you get

• Checks for mismatched identifiers, pack quantities, sizes, colors, capacities, conditions, brands and model numbers.
• A readable explanation and the original field evidence for every result.
• Optional semantic comparison through TypeSafe JEV using your own API key.
• JSON, CSV or Excel export through Apify, plus an aggregate run summary.
• A pair fingerprint and release version for tracing results.

This Actor audits candidate pairs you supply. It does not discover candidates, scrape websites, update product listings or change prices. It is decision support: review is a useful outcome when the supplied evidence is insufficient. Review recommendations before applying catalog changes.

Quick start

1. Paste product pairs into Product pairs. The supplied examples work without external setup.
2. Choose Rules only to inspect explicit differences, or TypeSafe JEV for semantic recommendations.
3. In JEV mode, enter your TypeSafe API key in the encrypted field. Create a key in your own TypeSafe account.
4. Set the maximum JEV calls and Apify run cost, then start the Actor.
5. Open Audit results, Field evidence or Usage and traceability. Export the dataset or inspect Run summary.

Example input

{
  "mode": "rules-only",
  "pairs": [
    {
      "id": "filter-pack-check",
      "left": { "title": "Filter F20 single pack", "brand": "ACME", "mpn": "F20", "packQuantity": "1" },
      "right": { "title": "Filter F20 six pack", "brand": "ACME", "mpn": "F20", "packQuantity": "6" }
    }
  ]
}

This returns review with attribute_conflict, identifies packQuantity, and makes no JEV call. Different strings can be synonyms or source errors, so the rule audit does not automatically declare a non-match.

For semantic matching, set mode to jev and supply typesafeApiKey. Put condition, accessories and pack contents in product titles when no dedicated field exists. Missing details are not assumed.

Input reference

Field	Default	Meaning
pairs	required	1–1,000 objects containing id, left, right
mode	rules-only	rules-only or jev
typesafeApiKey	none	Your encrypted TypeSafe key, required for JEV
threshold	0.95	Both model confidence and choice probability must meet this value; range 0.8–1
maxJevCalls	1000	Maximum TypeSafe requests in this run, range 0–1,000

Product fields: title, brand, mpn, gtin, size, color, packQuantity, condition, capacity. Values must be strings, up to 1,500 characters each. Each side needs a title, MPN or GTIN. GTINs must have a valid check digit and 8, 12, 13 or 14 digits; keep leading zeros. Pair IDs must be unique. Each pair is limited to 12 KB. Undeclared product fields are omitted.

How decisions work

1. Explicit attribute or identifier disagreements are flagged for review with the differing fields. No model call is needed.
2. In rules-only mode, all other pairs remain reviewable. This mode does not certify equivalence.
3. JEV evaluates unresolved pairs using only supplied product data. Low confidence or ambiguous evidence becomes review.
4. When the JEV call limit is exhausted, unresolved pairs have status: not_evaluated and reason: jev_call_limit. They are not charged as audited pairs.

evidence.comparison: different_text means the supplied values differ after basic text normalization, not that the physical products are necessarily different. A checksum-valid GTIN is not proof of authentic identifier assignment. Model confidence is not a measured accuracy guarantee. Model updates and different input detail may change recommendations.

Output

Each row contains id, left, right, decision, status, reason, explanation, evidence, conflictingFields, reviewRequired, method, model usage where applicable, pairFingerprint, release, elapsedMs and evaluatedAt.

SUMMARY reports requested, stored, audited and skipped pairs, decision counts, review rate, model calls, input tokens, estimated TypeSafe cost, completion and stop reason. Estimates exclude Apify charges, tax and manual work. Exported data retains user-supplied strings; treat spreadsheet cells as untrusted data and import them as text when needed.

Pricing

$3 per 1,000 audited product pairs ($0.003 each), plus $0.00005 per Actor start. Apify platform usage is included. A completed audit that recommends review is charged. Technical failures without a stored audited result and pairs skipped because of the JEV call limit are not charged as audited pairs. The start event can still apply to failed runs.

In JEV mode, TypeSafe bills your own API account separately. The Actor never supplies a shared seller key. At the published rate of $0.042 per million input tokens, 500 input tokens cost about $0.000021; actual token use depends on your input. Check current TypeSafe documentation and the Actor's Pricing tab before running.

The Actor checks Apify spending capacity before processing each pair, saves results with the audit event, and stops when the limit is reached. Set an appropriate run timeout for large batches. TypeSafe requests are sequential, with a 20-second timeout and no automatic retries.

Failures and reruns

Invalid input fails before pair processing. A provider or storage error stops the run; completed dataset rows remain available. An incomplete run may not have a summary. Inspect the log and dataset before retrying. Resuming a completed or partial run is not automatic: submit only the remaining IDs in a new run to avoid paying for repeat work. Failed TypeSafe requests may still incur provider charges. The configured TypeSafe call limit and Apify spending limit are separate controls.

Privacy and permissions

JEV mode sends the declared product fields and pair IDs to api.typesafe.ai. Arbitrary input URLs are never fetched. API keys are encrypted by Apify input handling and are not written to results or source. Only submit data you are authorized to process; do not put secrets or personal information in product fields. Input and results are stored by Apify according to your account settings. The Actor uses limited permissions and its own run storage.

Validation and support

Release 1.0 includes behavior and billing regression tests. A previous live integration test processed four synthetic pairs: one different and three review, including a same-product example held below threshold. These are integration checks, not a representative accuracy benchmark. No state-of-the-art or universal product-matching accuracy is claimed.

Report reproducible problems through the Actor's Issues tab, with the run ID and a redacted example. Never post API keys or private customer data. There is no guaranteed response-time SLA.