Metered Entitlements

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

Create a metered feature with a billable metric that measures consumption
Attach the feature to a price 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

curl -X POST "https://api.sandbox.paygentic.io/v0/features" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_abc123",
    "merchantId": "org_abc123",
    "name": "API Calls",
    "key": "api-calls",
    "type": "metered"
  }'

const response = await fetch('https://api.sandbox.paygentic.io/v0/features', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    productId: 'prod_abc123',
    merchantId: 'org_abc123',
    name: 'API Calls',
    key: 'api-calls',
    type: 'metered',
  }),
});

const feature = await response.json();

Linking to a price (entitlement template)

When creating or updating a price, include an entitlementTemplate to configure how grants are provisioned for subscribers:

cURL

curl -X POST "https://api.sandbox.paygentic.io/v0/prices" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "billableMetricId": "bm_xyz789",
    "model": "standard",
    "invoiceDisplayName": "API calls",
    "paymentTerm": "in_arrears",
    "properties": { "unitPrice": "0" },
    "feature": {
      "featureId": "feat_abc123",
      "entitlementTemplate": {
        "usagePeriod": {
          "interval": "P1M"
        },
        "issueAfterReset": 1000,
        "isSoftLimit": false,
        "resetMaxRollover": 0,
        "resetMinRollover": 0,
        "preserveOverageAtReset": false
      }
    }
  }'

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

curl -X PATCH "https://api.sandbox.paygentic.io/v0/plans/plan_def456" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prices": ["price_abc123", "price_ghi789"]
  }'

Entitlement template reference

Field	Type	Default	Description
`usagePeriod`	object	—	The reset cycle. Omit it for a one-time grant that doesn’t refill
`usagePeriod.interval`	ISO 8601 duration	required in `usagePeriod`	How often the grant resets. `"P1M"` monthly, `"P1D"` daily, `"P1W"` weekly
`usagePeriod.anchor`	datetime	subscription billing anchor	Reference point for computing period boundaries
`issueAfterReset`	number	—	Credits issued at the start of each period. If omitted with `usagePeriod`, `0`. If omitted without `usagePeriod`, no grant is provisioned
`issueAfterResetPriority`	integer	`0`	Burn order when multiple grants exist (lower = burned first)
`isSoftLimit`	boolean	`false`	If `true`, customer retains access even when balance reaches 0
`resetMaxRollover`	number	`0`	Max unused credits carried into the next period (`0` = use-it-or-lose-it)
`resetMinRollover`	number	`0`	Minimum credits that roll over, even when fewer remain
`preserveOverageAtReset`	boolean	`false`	If `true`, overage at reset is deducted from the next period’s balance. If `false`, overage is cleared at reset
`expiration`	object	—	`{ "count": 3, "duration": "MONTH" }` sets one fixed end at grant start + count × duration (`HOUR`, `DAY`, `WEEK`, `MONTH`, or `YEAR`). After it, the grant’s balance is 0 and it doesn’t refill

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.

curl -X GET "https://api.sandbox.paygentic.io/v1/entitlements/ent_abc123" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"

const response = await fetch(
  'https://api.sandbox.paygentic.io/v1/entitlements/ent_abc123',
  {
    headers: {
      'Authorization': 'Bearer sk_test_YOUR_API_KEY',
    },
  }
);

if (!response.ok) {
  throw new Error(`Entitlement check failed: ${response.status}`);
}
const entitlement = await response.json();
// { featureType: 'metered', balance: 750, hasAccess: true, ... }

Response example:

{
  "object": "entitlement",
  "id": "ent_abc123",
  "customerId": "cus_xyz789",
  "featureId": "feat_789",
  "featureKey": "api-calls",
  "featureType": "metered",
  "productId": "prod_abc123",
  "subscriptionId": "sub_abc",
  "status": "active",
  "activeFrom": "2026-01-01T00:00:00Z",
  "activeTo": null,
  "hasAccess": true,
  "metadata": {},
  "config": null,
  "balance": 750,
  "usageInPeriod": 250,
  "overage": 0,
  "isSoftLimit": false,
  "pricingUnitId": null,
  "currentPeriodStart": "2026-02-01T00:00:00Z",
  "currentPeriodEnd": "2026-03-01T00:00:00Z"
}

Response fields:

Field	Description
`id`	The entitlement ID
`featureKey`	The feature’s key, unique within its product
`featureType`	Always `"metered"` for metered features
`status`	Entitlement status: `active`, `expired`, or `canceled`
`hasAccess`	`true` when the entitlement is `active`, inside its `activeFrom`–`activeTo` window, and either `isSoftLimit` is `true` or `balance` is greater than 0
`balance`	Remaining credits across all active grants
`usageInPeriod`	Total usage consumed in the current period
`overage`	Usage beyond available credits
`isSoftLimit`	Whether access continues after the balance reaches 0
`pricingUnitId`	The credit pool’s pricing unit, or `null`. When set, `balance`, `usageInPeriod`, and `overage` are credits shared by every feature on that unit
`currentPeriodStart` / `currentPeriodEnd`	Current usage period boundaries. `null` for a one-time grant

An unknown entitlement ID returns 403 Forbidden, not 404.

Gating access

Check the balance before allowing an operation, then send the usage event regardless:

async function canMakeApiCall(entitlementId) {
  const response = await fetch(
    `https://api.sandbox.paygentic.io/v1/entitlements/${entitlementId}`,
    { headers: { 'Authorization': 'Bearer sk_test_YOUR_API_KEY' } }
  );
  if (!response.ok) {
    throw new Error(`Entitlement check failed: ${response.status}`);
  }
  const { hasAccess } = await response.json();
  return hasAccess;
}

// In your request handler
if (!(await canMakeApiCall(customer.entitlementId))) {
  return res.status(429).json({ error: 'API call quota exceeded' });
}

// Proceed with the request, then send a meter event
await fetch('https://api.sandbox.paygentic.io/v0/events', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'api.call',
    source: 'my-app',
    subject: customer.id,
    data: { quantity: 1 },
  }),
});

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

	Hard Limit (`isSoftLimit: false`)	Soft Limit (`isSoftLimit: true`)
When balance = 0	`hasAccess` returns `false`	`hasAccess` stays `true`
Best for	Strict quotas, free-tier caps	Overage billing, best-effort enforcement
Overage	Tracked in `overage` (events aren’t blocked), but not invoiced	Tracked in `overage` and invoiced at the price’s unit rate

Grant lifecycle examples

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

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

issueAfterReset: 1000, resetMaxRollover: 0, isSoftLimit: false

Date	Event	Balance
Jan 1	Grant issued	1000
Jan (mid)	600 credits consumed	400
Feb 1	Period reset — unused 400 forfeited, new 1000 issued	1000
Feb (late)	1000 credits consumed	0
Feb (late)	Another request	`hasAccess: false`

Example 2 — monthly grant with rollover cap

issueAfterReset: 1000, resetMaxRollover: 500, isSoftLimit: false

Date	Event	Balance
Jan 1	Grant issued	1000
Jan	Only 200 consumed — 800 remaining	800
Feb 1	Reset: 800 > 500 cap, rolled over as 500; new 1000 issued	1500
Feb	Heavy usage month	—

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

usagePeriod.interval: "P1D", issueAfterReset: 100, resetMaxRollover: 50

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.

Day	Event	Balance
Day 1	Daily grant issued	100
Day 1	80 consumed	20
Day 2	Reset: 20 ≤ 50 cap, rolls over; new 100 issued	120
Day 2	110 consumed	10
Day 3	Reset: 10 rolls over; new 100 issued	110

Example 4 — soft limit with overage carry-forward

issueAfterReset: 1000, isSoftLimit: true, preserveOverageAtReset: true

Date	Event	Balance	Overage
Jan 1	Grant issued	1000	0
Jan	1200 consumed	0	200
Jan 31	Access still allowed (soft limit)	—	200
Feb 1	Reset: new 1000 issued, 200 overage deducted	800	0

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

Example 5 — minimum rollover floor

issueAfterReset: 1000, resetMaxRollover: 100, resetMinRollover: 100

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

Jan usage	Remaining	Rolls over as
950	50	100 (raised to min)
900	100	100 (exact match)
200	800	100 (capped at max)

Rollover and overage reference

At each period reset, the carried-over balance of each grant is computed separately:

rolledOver = min(resetMaxRollover, max(resetMinRollover, currentBalance))

Ending balance	`resetMaxRollover`	`resetMinRollover`	Rolls over as
800	1000	0	800 (within range)
1200	1000	0	1000 (capped at max)
50	1000	100	100 (raised to min)
0	0	0	0 (use-it-or-lose-it)

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

Getting Started

Authentication

Platform

Integrations

Legal

Metered Entitlements

How it works

Setup

Creating a metered feature

Linking to a price (entitlement template)

Linking the price to a plan

Entitlement template reference

Checking the balance

Gating access

Soft vs. hard limits

Grant lifecycle examples

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

Example 2 — monthly grant with rollover cap

Example 3 — daily grants on a monthly subscription

Example 4 — soft limit with overage carry-forward

Example 5 — minimum rollover floor

Rollover and overage reference

Next steps

​How it works

​Setup

​Creating a metered feature

​Linking to a price (entitlement template)

​Linking the price to a plan

​Entitlement template reference

​Checking the balance

​Gating access

​Soft vs. hard limits

​Grant lifecycle examples

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

​Example 2 — monthly grant with rollover cap

​Example 3 — daily grants on a monthly subscription

​Example 4 — soft limit with overage carry-forward

​Example 5 — minimum rollover floor

​Rollover and overage reference

​Next steps

How it works

Setup

Creating a metered feature

Linking to a price (entitlement template)

Linking the price to a plan

Entitlement template reference

Checking the balance

Gating access

Soft vs. hard limits

Grant lifecycle examples

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

Example 2 — monthly grant with rollover cap

Example 3 — daily grants on a monthly subscription

Example 4 — soft limit with overage carry-forward

Example 5 — minimum rollover floor

Rollover and overage reference

Next steps