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

# Stock and alerts

> Read stock figures and get alerted before a set runs out.

## Stock figures

Every voucher set carries `stock`:

| Field | Meaning |
| - | - |
| `remaining` | Redemptions still possible: the sum of `maxRedemptions − redemptionCount` over redeemable vouchers. `null` means **unlimited** (at least one unlimited `multiple` voucher). |
| `used` | Redemptions so far (voided ones included) |
| `usagePercent` | `used / (used + remaining) × 100`, two decimals; `null` when unlimited or empty |
| `availableVoucherCount`, `expiredVoucherCount`, `revokedVoucherCount` | Voucher counts by status |
| `stockStatus` | `available`, `low` (from 90 % used) or `depleted` (nothing remaining) |
| `updatedAt` | When the figures were computed |

Stock figures are **eventually consistent**: they follow redemptions, uploads and revocations within about two minutes. The figures never decide a redemption: a redemption either gets a voucher or fails. `remaining` and `used` are 64-bit integers.

Read them on the set, or for all sets at once:

```bash theme={null}
curl -sS "$VOUCHER_API_BASE_URL/provider/v1/analytics/stock?sort=-stock.usagePercent&perPage=100" \
  -H "Authorization: Bearer $VOUCHER_API_KEY"
```

Consumers see only `stockStatus`, never your numbers.

## Threshold alerts

Each set has one stock alert rule, created with the set (thresholds 50, 75, 90 and 100 % used; the creating user as recipient, or your partner's operations contact when an API key created the set).

```bash theme={null}
curl -sS -X PUT "$VOUCHER_API_BASE_URL/provider/v1/voucher-sets/2030/stock-alert-rule" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"thresholds": [75, 90, 100], "recipientUserIds": [4043], "extraEmails": ["stock-alerts@example.com"], "enabled": true}'
```

* `thresholds`: any subset of 50, 75, 90, 100 (`[]` for none).
* `recipientUserIds`: up to 20 active members who can view voucher sets (others → `recipient-not-eligible`); `extraEmails`: up to 5 addresses.
* Each threshold fires **once** when usage crosses it, and is armed again when new vouchers lower the usage below it.
* Several thresholds crossed at once send **one** email listing them all.
* Thresholds you add at or below the current usage are marked as fired without an email.
* Each alert sends emails and the [`voucher-set-stock-threshold-reached`](https://docs-provider.voucher.allride.io/webhooks/events/voucher-set-stock-threshold-reached) webhook (`levels`, `usagePercent`). When nothing remains, you also get [`voucher-set-depleted`](https://docs-provider.voucher.allride.io/webhooks/events/voucher-set-depleted).

`GET …/stock-alert-firings` lists the alerts sent. Updating the rule needs `manage-provider-stock-alerts` and no change request.

## Unlimited sets

A set with at least one unlimited `multiple` voucher has `remaining: null` and `usagePercent: null`. Threshold alerts never fire for it; the rule shows `applicable: false`. It can still become depleted if those vouchers are revoked or expire.

## Related

* [Vouchers and uploads](https://docs-provider.voucher.allride.io/provider/vouchers-and-uploads.md)
* [Redemptions and analytics](https://docs-provider.voucher.allride.io/provider/redemptions-and-analytics.md)
* [Event catalog](https://docs-provider.voucher.allride.io/webhooks/events.md)


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