> ## Documentation Index
> Fetch the complete documentation index at: https://docs.needalert.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Use cases

> Integration walkthroughs: back in stock, appointment cancelled, items in sync and balance under control.

Four typical integrations, each with its sequence of calls. All of them use an API key token (see [Authentication](https://docs.needalert.app/en/api/authentication.md)) and the addresses from the [First request](https://docs.needalert.app/en/api/first-request.md) guide.

## 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](https://docs.needalert.app/en/api/external-reference.md) 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.

> [!NOTE]
>
> 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 with `insufficient_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](https://docs.needalert.app/en/establishments/credits.md).

## Variant: schedule instead of sending

For a set time ("cheese bread at 4 pm"), send `scheduled_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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.