Back in stock (ERP)
The shop’s ERP knows when a SKU’s stock is positive again. Every SKU that can run out is a one-time alert item (queue_type: single): whoever subscribed wants to know once, and the subscription ends with the alert.
1
When the product is registered, create the item
POST /establishments/{establishment}/items with external_reference equal to the SKU and queue_type: single. Nothing to store on your side: the reference is the bridge.2
When stock is back, find the item
GET …/items?external_reference=<SKU>. If subscribers_count is 0, there’s nobody to notify and you can stop here.3
Estimate and send
GET …/items/{item}/dispatch-preview for the cost; POST …/items/{item}/events with message and an Idempotency-Key derived from the ERP event (for example, the stock movement id), so a re-run of the job doesn’t send twice.Appointment cancelled (clinic scheduling)
Every specialty with a full schedule is a one-time alert item. Whoever wants an earlier slot subscribes through the QR code at the front desk or through the link.1
One item per specialty
external_reference with the specialty code in your system (for example, ORTHO).2
When a cancellation is recorded, send right away
POST …/items/{item}/events with the message about the open slot and an Idempotency-Key equal to the cancellation id. Every subscriber is notified at the same time; the first to call gets the slot.3
Follow up
GET …/events/{event} until dispatched, to record in your system how many people were notified (sent_count).Items in sync with your product list (online store)
The online store keeps Need Alert items mirroring its products, so the “notify me” button on the product page points to the right item.1
Sync in batches
For each product, the find, otherwise create pattern:
GET by reference, PATCH if it exists, POST if not. The 300 requests per minute per key allow large syncs; honor Retry-After on a 429.2
Update name and description
PATCH …/items/{item} with translations per language (pt_BR, en). The block of the chain’s default language always needs a name.3
Discontinued? Archive
DELETE …/items/{item}. The item goes offline, its subscriptions end and the reference is freed.Whoever clicks “notify me” in your store still signs in with their own Need Alert account (through the item’s
public_url). There is no subscription without login.Balance under control (finance)
A dispatch refused withinsufficient_credits is an alert that didn’t go out. Whoever looks after the balance can follow it through the API, with the manage_billing permission.
1
Read the balance
GET /tenants/{tenant}/credit-balance returns balance (credits available, one per person notified) and currency.2
Compare with recent consumption
GET /tenants/{tenant}/credit-transactions?type=consumption lists the debits, with a negative amount and event_id. If balance drops below the average cost of recent dispatches, warn the finance team.3
Buying stays in the dashboard
The API doesn’t buy credits: payment requires a person. See Credits.
Variant: schedule instead of sending
For a set time (“cheese bread at 4 pm”), sendscheduled_at in the POST …/items/{item}/events, within the schedule window of the dispatch-preview. The dispatch is born scheduled; reschedule it with PATCH …/events/{event} or cancel it with DELETE …/events/{event} while it hasn’t gone out. Two hours before, the owner and whoever can dispatch get a balance warning if it doesn’t cover the cost.