Set Up Entitlements: Plans, Subscriptions, and Usage
Three data models work together to describe what each account is entitled to and how much they consume — powering utilization and license views. This guide sets up Plans, Subscriptions, and Usage so their dimensions line up. Configure your Account model first; everything here hangs off accounts.
How they fit together
- Plans define the catalog and each plan's dimensions (limits like seats or API units, and feature flags).
- Subscriptions reference a
plan_idto inherit those defaults, and can override dimensions per account. - Usage reports consumption of those dimensions over time.
The one rule that ties them together: dimension names must match across all three.
1. Plans
Build the Plans model: one row per plan, mapping plan_id, name, type, and a dimensions JSON map (for example {"seats": 50, "api_units": 100000}).
2. Subscriptions
Build the Subscriptions model: one row per account's subscription, with plan_id (linking to a plan), the subscription type and validity window, and optional dimensions overrides where an account differs from its plan.
3. Usage
Build the Usage model: one row per account, dimension, and timestamp, mapping account_id, dimension, timestamp, and value. Each dimension must match a dimension key from the plan or subscription.
Keep dimension names stable
The most common mistake is a dimension named one way on the plan (api_units) and another in usage (apiUnits) — the rollups won't line up. Pick stable dimension strings and reuse them exactly across plans, subscriptions, and usage.