Back-in-stock alerts over iMessage for sold-out sizes

Who uses iMessage for back-in-stock alerts?

Back-in-stock alerts on ZeroSettle fit brands whose best sellers sell out by size: apparel and sneaker labels, small-batch food makers and limited runs, with a few hundred requests per restock from fans who mostly use iPhone. ZeroSettle is an iMessage API: a real phone number on real iMessage, running on Apple hardware we operate for you, that your code texts customers from and hears back on through a bearer token and signed webhooks.

The problem is reach at the moment of the restock. Gmail's Default inbox type sorts mail into categories automatically, putting "Deals, offers, and other promotional emails" in a separate Promotions tab, so a back-in-stock email can sit unseen while the size sells out again. A ZeroSettle alert lands in Messages, in a thread the fan started. Restock alerts are one of the commerce workflows in our list of iMessage use cases.

How iMessage back-in-stock alerts work, step by step

The fan starts the thread from your product page, your webhook stores the request, and your inventory system triggers the alerts. ZeroSettle carries the messages; the waitlist and stock logic stay in your code.

1. Next to each sold-out size, add a "Text me when it's back" button: an sms: link to your number prefilled with NOTIFY linen-set sage M (see how to get customers to text you first).
2. The fan taps Send. ZeroSettle posts a signed message.received event to your webhook about 1–2 seconds later. Your server stores the handle, product, size and time, and replies with a confirmation that names your brand.
3. When the size is back, your store's inventory webhook fires and your server loads every open request for it, oldest first.
4. For each requester, one at a time, your server calls POST /api/imessage/send with the product photo (image_b64) and a caption carrying the link.
5. A fan who replies HOLD gets the size reserved for 30 minutes. That is your store's logic, not a ZeroSettle feature.

Because every requester texted first, the link in the caption is tappable. The same link in a cold first text would show as plain text; see why links in a first iMessage aren't tappable.

Example conversation: one sold-out size

This thread shows one fan's request, the restock alert two weeks later and a HOLD, all in the thread the fan started.

Setup: NOTIFY requests stored from the webhook, sent on restock

The setup is a link on each product page plus one small server that stores NOTIFY requests and runs the restock loop. The signature check is copied from the webhook steps in the ZeroSettle docs.

<a href="sms:+18055550100&body=NOTIFY%20linen-set%20sage%20M">Text me when it's back</a>

On a fan's iPhone the link opens Messages with the text filled in. On Android it opens the SMS app, so keep an email sign-up next to the button.

# restock.py: run with  uvicorn restock:app --port 8100
import base64, hashlib, hmac, json, os, sqlite3, time
import requests
from fastapi import BackgroundTasks, FastAPI, Request, Response

BASE = os.environ.get("ZEROSETTLE_BASE_URL", "https://portal.zerosettle.io")
TOKEN = os.environ["ZEROSETTLE_TOKEN"]
SECRET = os.environ["ZEROSETTLE_WEBHOOK_SECRET"]
PRODUCTS = {"linen-set sage m": ("Linen Set, Sage, M", "https://maren.example.com/p/linen-sage", "linen-sage.jpg")}
db = sqlite3.connect("waitlist.db", check_same_thread=False)
db.execute("CREATE TABLE IF NOT EXISTS waitlist (handle, sku, msg_id, asked_at, alerted_at, PRIMARY KEY (handle, sku))")
app, seen = FastAPI(), set()

def verify(secret, header, raw_body, tolerance=300):
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        t, v1 = int(parts["t"]), parts["v1"]
    except Exception:
        return False
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

def send(body):
    while True:                                # the line sends one at a time
        r = requests.post(f"{BASE}/api/imessage/send", json=body,
                          headers={"Authorization": f"Bearer {TOKEN}"}, timeout=120)
        if r.status_code != 429 or r.json()["error"]["code"] != "line_busy":
            return r
        time.sleep(2)                          # line_busy: retry after 2 s

def on_text(msg):
    cmd, _, sku = (msg.get("text") or "").strip().partition(" ")
    sku = sku.lower()
    if cmd.upper() == "NOTIFY" and sku in PRODUCTS:
        # the opt-in record; a NOTIFY after an earlier alert reopens the request
        db.execute("INSERT INTO waitlist VALUES (?, ?, ?, ?, NULL)"
                   " ON CONFLICT (handle, sku) DO UPDATE SET msg_id = excluded.msg_id,"
                   " asked_at = excluded.asked_at, alerted_at = NULL WHERE alerted_at IS NOT NULL",
                   (msg["handle"], sku, msg["id"], time.time()))
        db.commit()
        send({"to": msg["handle"], "text": f"Maren Studio here. You're on the list for the "
              f"{PRODUCTS[sku][0]}. We'll text you here as soon as it's back."})
    elif cmd.upper() == "HOLD":
        row = db.execute("SELECT sku FROM waitlist WHERE handle = ? AND alerted_at IS NOT NULL"
                         " ORDER BY alerted_at DESC", (msg["handle"],)).fetchone()
        if row:                                # reserve a unit of row[0] here, or say it's gone
            until = time.strftime("%-I:%M %p", time.localtime(time.time() + 30 * 60))
            send({"to": msg["handle"], "text": f"Held for you until {until} \U0001F64C"})

def restock(sku):                              # call from your inventory webhook, in a background job
    name, url, path = PRODUCTS[sku]
    with open(path, "rb") as f:                # encode the photo once, not per fan
        photo = base64.b64encode(f.read()).decode()
    rows = db.execute("SELECT handle FROM waitlist WHERE sku = ? AND alerted_at IS NULL"
                      " ORDER BY asked_at", (sku,)).fetchall()       # oldest first
    for (handle,) in rows:
        r = send({"to": handle, "image_b64": photo, "image_format": "jpg",
                  "text": f"It's back! {name}: {url}"})
        if r.ok or r.json()["error"]["code"] == "recipient_opted_out":
            db.execute("UPDATE waitlist SET alerted_at = ? WHERE handle = ? AND sku = ?",
                       (time.time(), handle, sku))
            db.commit()
        # any other error leaves the request open; run restock(sku) again to retry it

@app.post("/webhook")
async def webhook(request: Request, tasks: BackgroundTasks):
    raw = await request.body()
    if not verify(SECRET, request.headers.get("X-ZeroSettle-Signature", ""), raw):
        return Response(status_code=401)
    payload = json.loads(raw)
    msg = payload.get("message") or {}
    if payload["event"] == "message.received" and msg["id"] not in seen:   # retries repeat the id
        seen.add(msg["id"])
        tasks.add_task(on_text, msg)
    return Response(status_code=200)

Register the receiver with PUT /api/imessage/webhook and store the signing secret it returns, which is shown only once. Send the product photo as a JPEG 1600–2048 px on its long edge: ZeroSettle sends a JPEG up to 2048 px exactly as you give it, re-encodes anything larger, and caps photos at 5 MB.

Limits and consent for back-in-stock alerts

Back-in-stock alerts never touch ZeroSettle's new-contact limit, because every requester texted the line first. The limit that matters is send time: one number sends one message at a time, normally 2–5 seconds each.

Our arithmetic from ZeroSettle's docs: a send takes "normally 2–5 seconds and at most about 75 for a text (about 105 for a voice message or photo, which ZeroSettle converts first)". The Growth column assumes requests spread evenly across three numbers, with one loop per number running at the same time.

• Don't send in parallel on one number. Concurrent sends queue and come back as 429 line_busy after about 12 seconds; retry after 2 seconds.
• Spread requests across Growth numbers as fans text in. A contact is always messaged from the line their conversation is on, so show different visitors different numbers on the button and requests for the same size land on every line. The code above is for one number; on Growth, also store the line_id each message.received carries and run one restock loop per line at the same time.
• Stop at two unanswered texts. The confirmation and the alert are two. A third, such as a "last few left" nudge, is refused with 403 awaiting_reply until the fan sends anything back. This cap applies on every plan.

Consent: the NOTIFY text covers this alert only

A fan's NOTIFY text is reasonably treated as their opt-in for that product and size, and the stored message is your record of it. It is generally not consent to marketing. This isn't legal advice; check your own situation with counsel.

• Ask before adding requesters to launch announcements. ZeroSettle's docs note that US marketing texts need written consent under the TCPA (the FCC's rules are in 47 CFR § 64.1200), with statutory damages of $500 to $1,500 per message for texting without prior express consent.
• STOP is enforced on every number. A text with the word STOP in it, or a clear request like "take me off your list", opts the fan out of every number on your account, and the alert to them returns 403 recipient_opted_out with nothing sent.
• Quiet hours. The docs ask that nothing promotional go out before 8 am or after 9 pm in the recipient's time zone. If stock goes live at night, have your restock job hold the alerts until morning.

When ZeroSettle is not a fit for back-in-stock alerts

ZeroSettle is the wrong tool for restock alerts in these cases:

• Your restock list runs to tens of thousands. At one message at a time, 10,000 alerts take about 6–14 hours on one number. Use email, push or an SMS platform.
• You'd add NOTIFY requesters to launch announcements without asking. ZeroSettle's terms prohibit high-volume marketing and unsolicited messaging, and ZeroSettle suspends lines used for unsolicited messaging.
• Many fans use Android. iMessage goes to iPhone and other Apple products, and ZeroSettle has no SMS fallback, so Android fans can't get the alert.
• You need every alert at one fixed time. ZeroSettle does not schedule sends, and with 300 requesters the last fan hears 10–25 minutes after the first.
• You need proof each fan saw the alert. The API reports message.sent and message.failed, not read status; see iMessage delivery status, webhook retries and latency.

How much does iMessage for back-in-stock alerts cost?

Back-in-stock alerts cost the plan price and nothing per message: ZeroSettle's outbound and inbound messages are unlimited (counted).

A brand alerting a few hundred fans per restock fits Pro; Growth fits when one restock draws more requests than one number reaches before the stock runs out. See the ZeroSettle pricing table or get a number. For selling in the same thread, see text-to-buy over iMessage and retail clienteling from store-owned numbers.