List 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.
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Query Parameters
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.
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.
pending, notified 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.
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.
1 <= x <= 100The 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.