# Tiers and freshness

Every field belongs to exactly one tier. No field is both stored and live. This is the single rule that shapes the API.

| Tier | Fields | Behavior |
|---|---|---|
| `graph` | title, brand, category, attributes, media, variants, recommendations | Stored and cacheable. Served from the graph, with an ETag and a short max-age. |
| `live` | exact price, exact stock, coupons | Fetched per request from the brand store. Never edge-cached (`no-store`). `as_of` tells you how fresh. |

## Why search cannot be live

You cannot fetch fifty million products to rank them on every query. So search, browse, and recommend read the `graph` tier. They are fast and cacheable.

Exact price and stock are volatile, so they are `live`: fetched on view and never trusted from a stale snapshot.

## Reading the tier

Check the `tier` field on the envelope, and the `Cache-Control` header:

- `tier: graph` and `Cache-Control: public, max-age=…` means you can cache it.
- `tier: live` and `Cache-Control: no-store` means it is a point-in-time number. Read `as_of`.

## The verified flag on price

Live price carries a `verified` flag. `verified: true` means the number came from the brand store just now. `verified: false` means the live fetch failed and you are looking at the last stored snapshot, so badge it as unverified rather than transacting blind.

## Next steps

- [Get live price](#/price): the live tier in practice.
- [The response envelope](#/envelope): how `as_of` and `tier` are surfaced.