# List restock alerts

`GET /api/v1/restock-alerts`

Every request to be told when a sold-out variant comes back, newest first. This is the record a restocking decision is made from, and NOTHING HAS EVER READ IT: the storefront writes a row when a shopper asks, the restock path claims the pending ones and mails them, and there is no admin route and no dashboard page, so "which sold-out variants have people waiting" was a database-console question until now. ONE LIST ANSWERS THREE QUESTIONS. ?variant_id= is "who is waiting on this", which is the purchasing question; ?status=pending is the live queue as opposed to the archive; ?email= is "what is this address waiting for", which is the shape a data-subject request arrives in. Send several to intersect them, or none for the store's whole waiting list, which is what a first sync wants. THE ALERT IS PER VARIANT, NEVER PER PRODUCT. A shopper waiting on one size is not waiting on the others, so a client that resolved variant_id up to its product would mail them about a restock they did not ask about. STATUS IS NOT TERMINAL. notified means this address has been told, but a repeat subscribe re-arms the same row back to pending and clears notified_at, because a shopper who wants to hear about the NEXT restock simply subscribes again. Treat notified as an archive you keep watching rather than as a closed record. AN ID OR ADDRESS THAT NAMES NOTHING IS AN EMPTY PAGE, not a 404, so this route is not a probe for which variant ids or which email addresses exist in the store. A ?status= outside the two values IS a 400, because that set is closed and a silently ignored status filter hands you the archive when you asked for the queue. PAGED BY CREATION TIME, which is the only column a re-arm never rewrites. Read created_at as "waiting since"; status and notified_at are what move. THIS FAMILY IS READ ONLY and there is no write half to add later. A row's whole purpose is to cause an outbound email from YOUR OWN sending domain the moment stock returns, so a caller-supplied address would be mail injection and would be indistinguishable afterwards from one a real shopper typed. Deleting a row is worse than silent: the shopper is simply never told and nothing reports it. Both stay on the storefront, where the person receiving the mail is the person asking for it, and apiscope mints no write_restock_alerts at all.

## Query parameters

- `variant_id` (string) — Narrow the page to everyone waiting on one variant, which is the purchasing question and the reason to integrate at all. A VARIANT, not a product: a shopper waiting on one size is not waiting on the others. NOT validated against the catalogue, so a variant nobody is waiting on and a variant that does not exist both return an empty page rather than a 404, which is what stops this being a probe for which variant ids exist.
- `status` (pending | notified) — pending is the live queue, notified is the archive. Omit it for both. A value outside the enum is a 400 rather than an unfiltered page, because a silently ignored status filter hands you the archive when you asked for the queue and you mail people who were already told. notified is NOT terminal: a repeat subscribe re-arms the row to pending.
- `email` (string) — Narrow the page to one address, which is what a data-subject request asks for. CASE IS FOLDED on both sides, so the mixed-case spelling a shopper typed matches the lowercased form this API stores and serves back. An address nobody subscribed with is an empty page, as with variant_id.
- `limit` (integer) — Rows per page. Out of range is a 400 rather than a silent clamp, so a client asking for more than 100 learns it did not get it.
- `after` (string) — The next_cursor from the previous page. Opaque: decode nothing from it and construct nothing by hand, since its encoding is not part of this contract. Omit it to read the first page.

## Responses

- `200` — Success
- `400` — The request was refused before any state changed. `code` is one of:

`invalid_body`, a write body this route will not take. `reason` partitions it
and `field` names the key when one key is at fault.
`invalid_query`, a query parameter, including limit and after.
`invalid_text`, a NUL byte or bytes that are not valid UTF-8 anywhere in the
path, the query or the body. Strip control characters before sending.
`idempotency_key_required`, a write sent without the Idempotency-Key header.
`invalid_request`, an Idempotency-Key longer than 255 bytes.

Routes add their own codes for rules only they know. Switch with a default arm.
- `401` — No credential, or one this API does not accept. `code` is always
`unauthorized`.

THE BODY IS DELIBERATELY UNINFORMATIVE. An expired key, a revoked key, a
publishable key, a key belonging to another merchant and a key that never
existed are all refused with the same bytes, so this response cannot be used to
probe which keys exist. Check the key's state in the dashboard rather than
inferring it here.

Send the key as `Authorization: Bearer <key>` or as `X-API-Key: <key>`. It is
never accepted in a query string.
- `403` — The key lacks the read_restock_alerts scope. `code` is `insufficient_scope` and the message names the scope to ask the merchant for.
- `429` — Too many requests. `code` is `rate_limited`.

Two limits apply independently: one on the credential and the route family,
one on the client address. The headers describe whichever has less left, so
honouring Retry-After always clears the window that bound.
- `default` — Any status this operation does not list, in the same envelope.

A 5xx means the request may or may not have applied. Retry it with the SAME
Idempotency-Key: that is the only way to find out without risking a duplicate,
and it is what the key is for.

A few 4xx conditions arrive here rather than as a listed status because they
depend on the merchant's plan or on a module being wired: 402 when a quota or a
plan limit is reached, and 503 when a capability the route needs is not
configured on this deployment. Both carry a `code` naming which.

## Example

```bash
curl --request GET \
  --url 'https://api.mercemur.com/api/v1/restock-alerts' \
  --header 'Authorization: Bearer <token>'
```