Amazon Offer Snapshot Freshness Audit

Check multi-seller Amazon offer snapshots you already have before you compare sellers. The Actor flags stale collection timestamps, mixed or ambiguous currencies, missing seller fields and duplicate rows, then tells you which ASINs are safe to compare.

It makes no network requests and does not scrape Amazon. It only reads the rows you paste or pipe into the input.

Who it is for

Teams that import offer exports from several collection runs or tools and repeat a sourcing comparison (for example weekly). Mixing a three-day-old row with a fresh one, or USD with EUR, quietly breaks the comparison. This Actor catches that first.

Input

Copy the prefilled input in the Console as a starting point.

Field	Meaning	Default
offers	Array of offer objects (max 5000)	required
referenceTime	ISO 8601 time to measure age against; empty = now	now
maxAgeHours	Older rows are stale errors	48
maxSpreadHours	Max gap between oldest and newest usable offer per ASIN	24
maxFutureMinutes	Clock tolerance for future timestamps	5
expectedCurrency	Optional 3-letter code; others are errors	none
requiredFields	Fields every row must have	asin, seller, price, currency, collected_at
minSellersPerAsin	Usable distinct sellers needed per ASIN	2

Recognised row keys (case and separators ignored): asin; seller, sellerName, sellerId, merchant, soldBy; price, amount; currency, currencyCode; collectedAt, scrapedAt, fetchedAt, capturedAt, timestamp; marketplace; condition. Timestamps may be ISO 8601 strings or epoch seconds/milliseconds. Timestamps without a timezone are assumed UTC and reported as info.

Output

The dataset has two kinds of rows (use the offers and groups views):

• offer rows: rowIndex, asin, seller, price, currency, collectedAt, ageHours, verdict (pass/warn/fail), issueCodes, issues.
• asin_group rows: usable offer and seller counts, currencies, collection spread in hours, comparisonReady.

A SUMMARY record in the key-value store holds verdict counts, issue counts, settings used, the comparison-ready rate and caveats.

Issue codes: missing_field, invalid_record, asin_format, invalid_price, currency_invalid, currency_symbol_only, currency_unrecognized, currency_from_price_text, currency_mismatch_expected, currency_mismatch_group, invalid_timestamp, timestamp_assumed_utc, stale_timestamp, future_timestamp, duplicate_offer, plus group codes mixed_currencies, timestamp_spread, too_few_usable_sellers.

Billing

The code emits one pay-per-event charge named offer-audited per audited row, only after the audit finished successfully. Invalid input or runtime errors end the run before any charge. The pricing itself is configured on the platform, not in this repository.

Limitations

• It validates data hygiene only. It cannot verify that a price, seller or stock status is true or still live.
• Freshness is judged from timestamps in your data; wrong or reused timestamps pass unnoticed.
• Currency checks use 3-letter codes. Symbols like $ or ¥ are ambiguous and only produce a warning; no exchange-rate conversion is done.
• The built-in currency list covers common codes; unlisted but well-formed codes get a warning.
• "Dominant currency" per ASIN is a majority vote, which is unreliable with 2–3 offers. Set expectedCurrency for small samples.
• comparisonReady is a rule-based signal, weak for ASINs with few offers. Defaults (48 h, 24 h, 2 sellers) are starting points, not benchmarks.
• Maximum 5000 rows per run; larger files must be split.
• Locale price parsing handles common 1,299.50 and 12,99 forms, not every regional format.

Local tests

The tests are offline and use only the standard library: python -m unittest discover -s tests -t .