What This Topic Solves
"Email me when it's back in stock" sounds simple enough when you say it out loud. Once the feature is actually running, though, a familiar set of complaints starts arriving: the same person got the alert three times, an alert that was supposedly sent never showed up, or the item was already gone by the time the email landed.
Most of these problems don't come from the wording of the email. They come from what happens before it. How do you decide that stock has genuinely returned? At what moment do you lock in the list of people to notify? When a send fails, who finds out and how? Skip those three decisions and you'll pay for it later in rework.
This series breaks the feature into three layers — detecting the inventory change, delivering the notifications, and running the admin screen. This page gives you the overall picture, and the three articles that follow go into each layer in detail.
The Four Stages Before an Alert Arrives
Receive inventory changes from Shopify and spot the moment a sold-out item has stock again
Match the item against people who asked to be notified, and line them up in a pending list
Send at a controlled pace, and retry the failures that are worth retrying
Show what was sent, what failed, and what is waiting to be retried in the admin screen
An alert moves through four stages: noticing the change, deciding who to send to, sending in order, and checking the result. If you can see at a glance which of the four a message is stuck at, you'll never wonder where to start looking when a question comes in.
Keep Four Kinds of Information Apart
For a restock alert system, splitting the data into four kinds from the very beginning keeps the design from buckling as requests pile up later. Those four: the sign-up records of people who want alerts, the record of inventory levels, the pending send list, and the record of what was actually sent.
Who wants to hear about which item
How many, and when (the basis for the decision)
When, to whom, what to send (the schedule of work)
Sent or failed (the retry history)
The top two are the information you make decisions with; the bottom two are the record of what you did. Keeping the sign-up list separate from the pending send list matters most. Because you freeze the recipient list at the moment stock returns, you can still tell which state is correct if someone opts out afterwards.
Series Articles (Deep Dives)
The design is covered in three layers. Reading them top to bottom also matches a sensible build order.
Reliable Back in Stock Detection Design (0 to 1)
How to spot only the moment stock returns, and the rules that keep the same alert from going out twice.
Notification Delivery Pipeline Design (Queue, Throttling, Retry)
Building delivery around a pending send list, pacing the sends, and handling retries after failures.
Back in Stock Admin UI Implementation Guide
Screen design for checking, retrying, and adjusting settings that an operations team can live with daily.
The Setup This Assumes
- Shopify (the source of truth for product and inventory data)
- Webhook (a mechanism that reports automatically when something like stock changes)
- A pending send list (a place to hold work so it can be processed in order)
- An email delivery service (the external service that actually sends the alerts)
- Next.js / Vercel (where the admin screen is served and the delivery work runs)
Where This Stands Today
In this repository, the delivery backbone and the admin screen for restock alerts have not been built yet. These articles exist to write down the design intent before work starts, so that development and operations share the same assumptions.
Outcome numbers, such as revenue attributed to alerts, are also treated as something to add once measurement is actually in place. Stating up front what exists today and what is still planned keeps readers from drawing the wrong conclusion.