# Enrich

Use this for a confirmed product that needs pricing; do not identify it again. If `identify` already returned usable `market` pricing for the same selection, reuse it. Include the returned `url` as a TCGplayer product link and reuse any image from the identity result. Enrich alone does not promise an image. See [result presentation](./agent-workflows.md).

`POST /api/v1/enrich` with `productId`, `productIds` (maximum 10), or a
`strataProductId`. TCGplayer IDs must be positive safe integers, not numeric
strings. Each priced item consumes one quota unit; a Strata ID without a
verified TCGplayer link returns `unsupported` and no fabricated raw price.

Optional selectors: `kind` (`card` or `sealed`), `printing`, `language`
(default English), and `condition` (NM, LP, MP, HP, DMG or Unopened).
Different printings and conditions are never pooled into a headline.

- `status`: `ok`, `partial`, or `no_data`.
- `sources`: separate status for prices, sales and listings.
- `selectionRequired`: choose a printing/condition from `valuations` when true.
- `valuations`: comparable sales/listings grouped by printing, language and condition.
- `printings`: provider market and listed-median benchmarks for each printing.
- `currency`: USD; `fetchedAt`: observation time; `cacheAgeSeconds`: freshness.

The provider's market price is an aggregate benchmark, not a condition-specific
sale. If absent, the listed median is explicitly labeled as an asking-price
benchmark. Do not compare it as though it were a recent completed sale.

Sales and listings must match the selected printing, language and condition.
Missing language or shipping is excluded rather than assumed. A sample of the
50 cheapest listings may miss suitable listings; `null` does not prove none exist.

Custom listings may describe components. Obvious component titles and implausibly
low asks are excluded. With no benchmark, custom listings are unverified. These
heuristics and seller status cannot guarantee authenticity; exclusions are auditable.

All-source outages return an error. Partial results identify unavailable sources
and are not cached as complete results. Complete pricing is cached up to five
minutes. A repeat of the exact same single-product request on one account within
30 seconds replays the first successful response without another credit or audit
event (`X-Strata-Replayed: true`). Other cache hits consume normal credits.
Requests with an explicit `Idempotency-Key` keep that key's retry semantics.
Raw cards and sealed products only; never value a graded slab using these
prices. Use `/api/v1/graded/prices` for a verified graded market. The upstream
marketplace endpoints are undocumented.

`Foil` and `Holofoil` are normalized to `Foil` across provider data and request
selectors. Reverse Holofoil and specialty finishes remain distinct. Original
provider labels remain available as `rawPrinting` or the sales `variant` field.