Skip to main content
Metered entitlements give customers a credit grant when they subscribe. As they consume resources—API calls, compute minutes, storage operations—usage events deplete the grant. At any point, you can query the balance to see how many credits remain and whether the customer still has access. Unlike static entitlements (which grant a fixed configuration value), metered entitlements track consumption against a grant that can refill each usage period.

How it works

  1. Create a metered feature
  2. Attach the feature to a price that measures a billable metric (billableMetricId), with an entitlement template defining the grant amount, reset period, and rollover rules, then add the price to a plan
  3. Customer subscribes → a grant is provisioned automatically for the current period
  4. Your app sends usage events as the customer consumes
  5. Call the balance endpoint to check remaining credits and gate access

Setup

Creating a metered feature

Linking to a price (entitlement template)

When creating or updating a price, include an entitlementTemplate to configure how grants are provisioned for subscribers:
cURL
With a feature attached, a metered price invoices only overage, and only for a soft limit. Usage inside the grant isn’t charged. A unit price of "0" also makes overage free, which is the typical setup when you use metered entitlements for quota enforcement rather than per-event billing.

Linking the price to a plan

prices replaces the plan’s whole price list, so send every price ID the plan keeps, not only the new one. The change creates a new plan version.
cURL

Entitlement template reference

When a subscription starts mid-cycle, the first, partial period gets a one-time grant of issueAfterReset scaled to the part of the period that remains, rounded down. The full grant starts at the billing anchor. Credits left from the partial grant don’t roll over.

Checking the balance

Use GET /v1/entitlements/{entitlementId} to get a snapshot of the balance. Paygentic calculates it from aggregated meter data when you request it. Meter events are processed asynchronously, so an event you just sent can take a short time to count.
Response example:
Response fields: An unknown entitlement ID, or one that belongs to another merchant, returns 404 Not Found.

Usage dated in the past

An allowance measures usage from the entitlement’s start or from the moment Paygentic creates the entitlement, whichever is later. When the subscription has a test clock, that moment is the test clock’s time. Usage dated earlier never counts against the allowance, even if you send it afterwards. The event is still accepted with 202 and still shows on the metric’s meter, so the meter and the allowance can disagree. A metered entitlement (GET /v1/entitlements/{id} and GET /v1/entitlements) tells you where the cutoff is:
Usage dated before the cutoff
If your usage is dated before usageCountedFrom, it isn’t counted. An event dated exactly at usageCountedFrom is counted, and is not in the link. The link’s total covers every event on the metric for this customer, so it can include usage that an earlier entitlement already counted, from an earlier subscription or from before a plan change. This includes a subscription with a startedAt in the past. For a price with a metered feature, usage dated before you create the subscription never draws down the allowance and is never billed, whichever elapsedPeriodBilling value you choose. See Starting a subscription in the past. To build a usage history, for example in the sandbox, use a test clock: start the clock in the past, send usage dated at the clock’s time, and advance the clock. See Simulating time.

Gating access

Check the balance before allowing an operation, then send the usage event regardless:
type must match the eventType of the billable metric on the price, and subject is the Paygentic customer ID. See Meter Events for the full event format.
The grant engine doesn’t block usage events. Always check hasAccess before allowing an operation—don’t rely on the event pipeline to enforce limits.

Soft vs. hard limits

Grant lifecycle examples

These examples show how grants behave across billing periods under different configurations.

Example 1 — monthly grant, use-it-or-lose-it

Example 2 — monthly grant with rollover cap

The rollover is applied before the new grant, so the customer starts the period with rollover + issueAfterReset.

Example 3 — daily grants on a monthly subscription

A customer’s subscription renews monthly, but their grant resets daily. Each day they receive a fresh allocation. A reset interval that differs from the billing cadence isn’t allowed on a price with grantDiscountEnabled.

Example 4 — soft limit with overage carry-forward

The preserveOverageAtReset flag ensures customers who overconsume one period have a reduced allowance the next period.

Example 5 — minimum rollover floor

When both min and max rollover are set to the same value, customers always carry forward exactly that amount regardless of actual usage:

Rollover and overage reference

At each period reset, the carried-over balance of each grant is computed separately:
A grant’s balance never goes below 0: usage beyond it is recorded as overage. If resetMinRollover is greater than resetMaxRollover, the result is always resetMaxRollover. A grant that ends at or before the reset doesn’t roll over. When preserveOverageAtReset is true, the previous period’s overage is deducted after rollover: it burns the rolled-over credits first, in burn order, and then the new grant. When it’s false, the overage is discarded at reset. Grants you add with POST /v1/entitlements/{id}/grants default to priority 0, the same as the template grant, and they keep their unused balance at reset. See Grants.

Next steps