# Entitlements & features (https://docs.billwave.example/pricing/features)

Entitlements & features [#entitlements--features]

In Billwave, **features** are the capabilities in your product and **entitlements** are the rules that grant those capabilities to a customer.

Feature types [#feature-types]

* `boolean`
  * On/off access (e.g. "Analytics Dashboard", "API Access")
* `metered`
  * A limit that can be checked and incremented. These are **consumable** features (e.g. "API Calls", "Emails Sent").
* `entity` (non-consumable)
  * Persistent resources that are added and removed. These are **non-consumable** features (e.g. "Seats", "Projects", "Workspaces").
* `static`
  * A fixed value (configuration) (e.g. "Environment Variable", "Support Level").

Consumable vs. Non-consumable [#consumable-vs-non-consumable]

Billwave distinguishes between features that are "used up" and features that represent "capacity":

Consumable features (metered) [#consumable-features-metered]

These features reset on a schedule (e.g. 1,000 emails per month). When you call `track()`, usage increments and the remaining balance decreases. Once the limit is reached, access is blocked or overages are charged.

Non-consumable features (entity) [#non-consumable-features-entity]

These features represent persistent items that you manage. Instead of `track()`, you use `add()` and `remove()`.

* **Seats:** Add/remove users from an organization.
* **Projects:** Create/delete projects in a workspace.
* **Limits:** If you have a limit of 5 seats, you can have up to 5 users active at any time. Removing one user frees a slot for another.
* **Reset:** These features default to `reset: "never"` because they represent current state, not periodic usage.

Where entitlements come from [#where-entitlements-come-from]

* A customer’s active subscription plan
* Optional customer-level overrides

Runtime access checks [#runtime-access-checks]

Use `check()` to decide whether to allow an action.

```ts
const { allowed, code, balance } = await billwave.check({
  customer: "user_123",
  feature: "api_calls_monthly",
});
```

* `allowed` is the main signal you should gate on.
* `balance` is useful for UX (show usage).
* `code` helps you decide *why* access was denied (upgrade, top-up, etc.).

Response codes [#response-codes]

* `access_granted` — the customer has access
* `limit_exceeded` — usage limit has been reached
* `feature_not_in_plan` — the feature is not available on the current plan
* `no_active_subscription` — the customer has no active subscription

Usage tracking [#usage-tracking]

If a feature is metered, call `track()` to record usage.

```ts
await billwave.track({
  customer: "user_123",
  feature: "api_calls_monthly",
  value: 1,
});
```

Overrides [#overrides]

Billwave allows you to override entitlements at the **customer** level. You can grant specific features to a customer regardless of their plan — useful for grandfathering early users or giving beta access.