How it works
- Create a metered feature
- 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 - Customer subscribes → a grant is provisioned automatically for the current period
- Your app sends usage events as the customer consumes
- 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 anentitlementTemplate 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
UseGET /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.
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 with202 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
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.
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
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
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
- Grants — Add credits mid-cycle via direct creation or paid purchase
- Features and Entitlements — Feature types and automatic provisioning
- Meter Events — Send usage data that powers metered entitlements
- Billable Metrics — Define what you measure