# Products, identities and mappings

`GET /api/v1/products/{id}` reads a Strata product and its current capabilities or registry progress. Use the `strataProductId` UUID returned by identification; a numeric TCGplayer ID is not a Strata UUID. This authenticated read uses no lookup credits. It does not identify arbitrary text or create a mapping on demand.

## Keep identifiers distinct

| Identifier | Represents | Next use |
| --- | --- | --- |
| `productId` | Numeric TCGplayer catalog product; printing may still require selection. | Raw/sealed `enrich`; explicit catalog confirmation. |
| `strataProductId` | Strata UUID returned by identity resolution. | Product capabilities, verified raw/graded pricing. |
| `identityRef` | Provider identity, such as an ALT asset. | Pass as `ref` to graded pricing. |
| `cert` and grader | A particular graded copy's certification evidence. | Slab identification. |
| `resultRef` | Account-bound evidence for a past identification, not a product. | Feedback during its retention period. |
| `mappingRevision` | Revision of an observed cross-market relationship. | Detect changed mappings before reusing a comparison. |

A physical slab, an underlying card, a catalog product and a market selection are different things. Two copies can share the same underlying market without sharing a cert. A catalog product can contain finishes that map to different graded assets.

## Read capabilities before composing markets

Inspect `capabilities` and `rawMatch` rather than assuming every product supports both price sources. `rawMatch.status` distinguishes:

| State | What the agent should do |
| --- | --- |
| `verified` | Use the returned link and its exact printing/language selectors. |
| `queued` / `resolving` | Preserve the original result. A bounded later read may observe progress. |
| `review_required` | Explain that a mapping needs review; do not infer a price through it. |
| `unmapped` | Show the available market without a cross-market comparison. |
| `unsupported` | Explain the coverage limitation; do not substitute another language or edition. |
| `unavailable` | Treat as a service failure, not proof that no mapping exists. |

When available, honor `retryAfterSeconds`. Poll only while the user is waiting for that product, with a bounded stop condition. Do not continuously crawl registry progress.

## Slab to raw

Resolve the slab through `/api/v1/slabs/identify` first. Keep the graded result even when no TCGplayer match exists. After the registry supplies a verified raw mapping, call `/api/v1/enrich` with the returned Strata UUID and the desired raw condition. The API enforces mapping selectors; conflicting selections return 409. Label the result “Raw · Near Mint reference” when using NM. Slab grade does not establish raw condition.

## Raw to graded

After raw identification, choose the actual printing and language. Request `/api/v1/graded/prices` with `strataProductId`, `rawProductId` and `rawSelection` matching that verified link, plus explicit grade markets. Once the link and selectors are known, raw and graded pricing may run concurrently. Do not fall back to a similarly named ALT asset when a link is absent.

See [recipes](./recipes.md), [graded prices](./graded-prices.md), [registry feedback](./registry-feedback.md), and [endpoint schemas](./api-reference.md).