- Subscribe customers to the exact variant when their choice matters.
- Accepting a request does not prove that a notification was sent.
- Recheck whether the item is genuinely purchasable immediately before sending.
- Make processing safe when workers or requests repeat.
- Expose the queue and cancellation history to operators.
Inventory state was only the beginning of the feature
Medusa could tell the storefront that an item was unavailable. The client still needed to capture the customer’s exact choice, avoid duplicate requests and prefill known customer details. It also needed cancellation, processing rules and an operator view of the queue and failures.
We built variant-aware subscriptions with guest and authenticated flows, database uniqueness for open alerts, processing states, unsubscribe tokens and email rendering. A Medusa Admin queue supports manual processing. The processor rechecks stock before requesting an email. Provider acceptance and inbox delivery still require their own evidence.
The small form contains a long-lived promise
A customer enters an email because a product is unavailable. The company has implicitly promised to remember the request, watch the correct item and contact the customer when buying is possible again. That promise may live for weeks. During that time, variants change, stock moves, products are unpublished and processing can fail.
We separated the journey into clear stages: request accepted, subscription stored, item eligible, message requested and final outcome. This prevents one green response from doing too much rhetorical work. An HTTP success can mean only that the website accepted the form. It does not prove that a row was stored, an email provider accepted a message or the customer received it.
Subscribe to the choice the customer actually wants
A shirt may be available in red but unavailable in the blue size chosen by the customer. A product-level alert can therefore send a technically true but commercially useless message. When the interface captures a variant choice, persist that exact identity and recheck that variant before notification.
If the product has no meaningful variants, product-level subscription may be enough. The rule should follow the customer promise, not the easiest database key. Store a stable commerce identifier and safe display context, but do not freeze current stock or price as truth. Those facts are resolved again when the alert is considered for sending.
One customer request should create one active subscription
Customers click twice, browsers retry and forms may be submitted again days later. The same normalised email and variant should not create several active subscriptions. Enforce that rule in the database, not only with a ‘check then insert’ sequence that two simultaneous requests can both pass.
A repeated request can reassure the customer and refresh consent information without revealing whether an address already exists. Privacy matters because the endpoint is public. Rate limits, input validation and neutral responses reduce abuse and prevent the form from becoming a way to discover who subscribed.
Stock greater than zero is not always sellable
Immediately before sending, check that the variant is published, available in the relevant sales channel and market, has a usable price and satisfies the business inventory rule. A raw quantity can be positive while the item remains reserved, disabled or unavailable to that customer’s region.
Decide how long availability must remain stable, whether preorders qualify and what happens when only a few units return for thousands of subscribers. Sending in controlled batches may be fairer and safer than notifying everyone at once. The notification rule should match the promise in the form, such as ‘available to order’ rather than the vague ‘stock changed’.
Make repeated processing harmless
A worker can stop after asking the email provider to send but before marking the subscription complete. On retry, it may send again. The processing system therefore needs to claim work safely and use a stable message identity that the provider or application recognises. Attempts can repeat; the intended customer notification should not.
Persisted states, operator visibility and unsubscribe mechanics make the queue understandable. Scheduling, safe work claiming and provider feedback then complete the operating path. A record marked sent should distinguish provider acceptance from confirmed inbox delivery so the team always knows what the status actually means.
Cancellation is part of the feature
Every alert needs a safe cancellation route using an opaque token rather than an exposed database identifier. Unsubscribing should be harmless to repeat and should win over a send that has not yet been committed. The system retains only the history required for consent, suppression and support.
Product pages should also let a returning customer understand whether they already requested an alert without exposing subscriber information publicly. Consent wording needs to say whether the address is used only for this alert or also for marketing. A stock notification request is not automatic permission for a newsletter.
What operators need to see
Operators need counts of waiting, eligible, processing, sent, failed and cancelled subscriptions, plus the age of the oldest waiting item and repeated failures by template or product. They should be able to inspect attempts without seeing unnecessary personal data and retry only states known to be safe.
Alert on a queue that stops moving, a sudden increase in provider rejections and subscriptions waiting despite sellable stock. The useful question is not ‘did the cron run?’ It is ‘are customers who were promised an alert moving towards one clear outcome?’ That framing keeps technical monitoring connected to the customer commitment.
The back-in-stock checklist
Define product or variant precision, normalise and deduplicate requests, record consent, recheck sellability, claim work safely, make sending repeat-safe, offer unsubscribe and expose attempts to operators. State retention and retry limits explicitly.
Test simultaneous subscriptions, stock disappearing during processing, worker failure after provider acceptance, unsubscribe racing with send and an unavailable market. A reliable alert is not proved by a successful form submission or attractive email preview. It is proved by the complete path from customer request to one justified outcome.
Common questions
Use the level the customer selected. If size or colour matters, attach the request to the exact variant so the message is genuinely useful.
Not necessarily. It means the request was accepted. Persistence, eligibility, provider acceptance and inbox delivery are separate stages that need their own evidence.
Only with separate, valid consent. Asking for one stock notification is not the same as subscribing to ongoing marketing.