Plans and features

A plan describes the commercial offer. A feature describes what your product checks or meters. A plan-feature assignment joins them into an entitlement.

Catalog groups the resources that define an offer. Use its shortcuts to move into plans, features, add-ons, or shared credit systems.

Feature types

• BOOLEAN grants or denies access.
• METERED records quantities and can enforce quotas or overage rules.
• ENTITY represents countable product resources such as projects or seats.
• STATIC exposes plan metadata without metering.

Metered entitlements

Metered features can define an included quota, reset interval, overage policy, and rating model. Usagey supports package, volume, and graduated rating behavior.

• PACKAGE charges a fixed price for each block of units. For example, a package size of 1,000 and a package price of $10 charges $10 when overage enters the first block and another $10 only after it exceeds 1,000 units.
• VOLUME applies the rate from the final reached tier to all overage units.
• GRADUATED prices each portion of usage at the rate for its tier.

Package size defaults to 1, preserving ordinary per-unit behavior for existing assignments. Usagey calculates package, volume, and graduated charges from cumulative overage and records only the charge delta, preventing repeated tracking calls from billing the same block twice.

Use stable feature keys such as api_requests or storage_gb. Your backend sends that key to both /v1/usage/check and /v1/usage/track.

Plan groups

Plans in the same group are mutually exclusive for a customer. Use a group for upgrade and downgrade paths such as Free → Starter → Pro.