Entitlements
Entitlements define the features and usage rights a customer receives based on their subscription plan, addons, and any manual overrides. Use entitlements to control access, drive monetization, and offer flexible packaging.
In This Section
- Overview — What entitlements are and how they work in BillHive.
- Features Overview — Understand feature types (Switch, Quantity, Range, Custom) and properties.
- Feature Management — Create, edit, activate, and delete features.
- Product Entitlements — Attach features to rate plans and addons with specific values.
- Subscription Entitlements — View resolved entitlements, add overrides, and re-resolve.
- Customer Entitlements — Grant features directly to customers outside of subscriptions.
Wallet Exhausted (Prepaid Credits)
When a subscription’s price uses prepaid credits with the zero-balance action Block further use, BillHive tells you when the wallet is used up, so your product can stop service.
How to read it
| Where | Field |
|---|---|
v1 GET /subscriptions/{subscriptionId}/entitlements | Response header X-Wallet-Exhausted: true or false |
v1 POST /subscriptions/{subscriptionId}/entitlements/resolve | The same X-Wallet-Exhausted header |
v2 GET /v2/subscriptions/{id}/wallet | walletExhausted in the body |
GET /subscriptions/3f1c2a64-9a1e-4a58-8d52-0f5d6a9d2b11/entitlements
Authorization: Bearer YOUR_API_KEY
HTTP/1.1 200 OK
X-Wallet-Exhausted: true
Content-Type: application/json
[ /* the entitlements, as before */ ]The response body does not change, so existing integrations keep working. The header is set only when the value could be read. If the read fails, the header is left off and the list is still returned.
When it is true
- The price’s action is Block further use, and
- the projected balance reached 0 at the last check (the daily job, or the check after a drawdown).
A price without a wallet, or with another action, reports false. The flag clears at once when credits arrive: a paid top-up, an adjustment, or a renewal grant.
Block is a signal. Usage that happens anyway is still billed as overage. See Zero-Balance Actions.