# get_sunglasses_offers

Return covered US offers for one exact variant with item price, shipping, tax, landed-total status, availability and observation time, each kept separate.

- REST: `GET https://sunglassesguides.com/api/v1/variants/{variant_id}/offers` (OpenAPI operationId `get_sunglasses_offers`)
- MCP: tool `get_sunglasses_offers` on `https://sunglassesguides.com/mcp`
- Read-only: yes. It never changes anything outside this service.
- Market / units: US, USD, millimetres. Schema version 1.0.
- Support: implemented=true, data_covered=no, externally_verified=false. No approved merchant/affiliate feed is connected yet. Production returns NO_OFFER_COVERAGE.

## When to use

- The user needs a purchase option for a specific variant.

## When not to use

- To find the cheapest price on the web (not supported).
- To check spec facts (use get_sunglasses_variant).

## Input

Path parameters: `variant_id`. Query parameters: `ship_to_zip`, `market`, `expected_data_version`.

| Name | Type | Required | Range | Meaning |
|---|---|---|---|---|
| `variant_id` | string | yes |  | Stable variant_id from this catalog, e.g. returned by find_sunglasses or resolve_sunglasses. |
| `ship_to_zip` | string | no | max 10 chars | Optional 5-digit US ZIP to evaluate shipping coverage. |
| `market` | string | no | max 8 chars | Market code. Only "US" is supported; anything else returns 422 UNSUPPORTED_MARKET. |
| `expected_data_version` | string | no |  | data_version returned by an earlier call. If the catalog changed since, the call fails with DATA_VERSION_CHANGED instead of mixing old and new facts. |


## Output

The standard envelope (see [REST conventions](https://sunglassesguides.com/docs/rest.md)): `request_id`, `success`, `schema_version`, `data_version`, `data_mode`, `generated_at`, `request`, `result`, `sources`, `freshness`, `cache`, `next_actions`, and `error` on failure.

status OFFERS_FOUND or NO_OFFER_COVERAGE with an empty list. Never returns simulated prices in production.

`result.status` values: `OFFERS_FOUND`, `NO_OFFER_COVERAGE`. `success:true` means the request was processed; it does not mean something matched.

## Sources and time

Each field carries `field_status`, `source_ids` and evidence excerpts; `sources[]` lists each cited source once with `retrieved_at`. `checked_at` is per record. See [freshness](https://sunglassesguides.com/docs/freshness.md).

## Permissions

Anonymous read-only trial without a key; optional API key for higher quotas. See [auth and quotas](https://sunglassesguides.com/docs/auth-and-quotas.md).

## Examples

### Example

```sh
curl -sS https://sunglassesguides.com/api/v1/variants/rayban-rb2140f-8053672054682/offers
```

With no approved price source connected this returns `result.status` `NO_OFFER_COVERAGE` and `offers: []` (HTTP 200). It never returns simulated prices in production.

Invalid ZIP: `curl -sS 'https://sunglassesguides.com/api/v1/variants/rayban-rb2140f-8053672054682/offers?ship_to_zip=abc'` returns HTTP 422 `VALIDATION_FAILED`.

## Related tools

- [get_sunglasses_variant](https://sunglassesguides.com/docs/get_sunglasses_variant.md)
- [find_sunglasses](https://sunglassesguides.com/docs/find_sunglasses.md)