Product, SKU and evidence
productId identifies a catalog product; skuId identifies its condition, variant and language. Preserve all four values when comparing prices. Product-level aggregate prices are a different signal from an exact SKU observation. Listing prices use US shipping context.
matchScore ranks heuristically; match records name/cardNumber/set evidence. Explicit collector-number conflicts are excluded. exactMatchProductId is populated only for a unique verified exact candidate, with no truncated retrieval. Confirm the physical card and sellable finish before applying any market value.
Bounded coverage
Identification inspects at most 50 products without a collector number and 200 with one. Only a unique exact normalized set-name match narrows search; fuzzy hints rank broad results. setResolution distinguishes unmatched and unavailable set hints. Inspect truncated and searchedCount. A null totalSearchResults means coverage is unknown and prevents a verified exact match. No candidates does not prove catalog absence.
Catalog search has offset 0–10,000 and limit 1–50. Category/set filters require lowercase slugs, while identification accepts a set-name hint. priceCoverage lists requested and missing SKU IDs: missing is not an authoritative zero-price observation.
Three timestamps
observedAt is response assembly time. fetchedAt is local completion of a section fetch, including an older cached observation. calculatedAt is the source calculation time when available. These timestamps are not interchangeable. cacheHit records cache reuse; stale records reuse after a transient source failure.
Default per-process caches: details/history 15 minutes, prices/search 2 minutes, listings/featured offers 30 seconds, successful image checks/categories 24 hours; absent-image checks 30 seconds. Transient failures may retain explicitly stale data for up to 5 additional minutes. This is a freshness policy, not a source publication guarantee; replicas can have different cached observations.
Unknown and empty values
Unknown amounts, counts and source fields remain null. Successful empty history/listings retain their object envelopes. The details route leaves imageUrl null; use /image or the snapshot for a checked URL. Returning an image URL does not establish display or redistribution permission.