Entitlements

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

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

WhereField
v1 GET /subscriptions/{subscriptionId}/entitlementsResponse header X-Wallet-Exhausted: true or false
v1 POST /subscriptions/{subscriptionId}/entitlements/resolveThe same X-Wallet-Exhausted header
v2 GET /v2/subscriptions/{id}/walletwalletExhausted 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.