Usage metering

A usage feature needs a meter. The meter selects an event, reads its measured properties, and aggregates them for the customer’s entitlement. Flat, tier, and package features do not need a usage meter.

Events, meters, and features

Concept	Purpose	Example
Event	Records an action from your application	A `completions` event
Meter	Selects and aggregates a measured property	Sum `outputTokens`
Feature	Names the capability you sell or limit	`ai-output-tokens`

Use eventSlug for the action and properties for its measured values. Use featureSlug when checking or consuming one specific feature. One asynchronous event can update several matching feature meters:

const { error } = await unprice.usage.record({
  customerId: "cus_1234567890",
  eventSlug: "completions",
  idempotencyKey: request.id,
  properties: {
    aiMessages: 1,
    inputTokens: 1840,
    outputTokens: 620
  }
});

if (error) throw new Error(error.message);

For example, a message meter can sum aiMessages while an output-token meter sums outputTokens. Configure each usage feature with its event slug, aggregation method, and aggregation field.

Aggregation methods

Method	Result	Use for
`sum`	Sum of the reported numeric field	Tokens, bytes, or seconds
`count`	Number of matching events	API calls, jobs, or exports
`max`	Highest reported value	Peak storage or peak active users
`last`	Latest reported value	An absolute resource snapshot

sum, max, and last need an aggregationField. count counts events rather than reading a numeric field. Retries of the same event must use the same idempotencyKey.

Quota resets and billing periods

A quota window controls when a customer’s usage allowance resets. A billing period controls when charges are invoiced. These can differ, for example a daily allowance on a monthly subscription. Configure the feature’s reset cadence separately from its billing cadence. Do not assume that an invoice date also resets every usage limit. Use access.check to inspect current usage, limit, and quotaWindow. The window contains startAt, endAt, and periodKey; timestamps use epoch milliseconds. A null endAt means the window has no end. A null quotaWindow means active grants do not share a single reset window. Use usage analytics for historical reporting, not as a live spend gate.

Report usage or authorize work

Use usage.record after an action when you need asynchronous metering and evidence. It does not prevent over-budget work.
Use usage.consume before an action when its usage amount is already known. Check allowed before starting the work.
Use a budgeted run when the final amount is unknown before work starts. Reserve first, then settle actual usage when the workload finishes.

A read-only access.check does not consume an allowance or reserve money. Two concurrent requests can both pass a read-only check. Use an enforcing operation for spend control.

Report resource snapshots

For resources such as active seats or stored bytes, report the absolute value from your own system. Configure max to track the highest reported value or last to track the latest one.

const { error } = await unprice.usage.record({
  customerId,
  eventSlug: "active_seats_snapshot",
  idempotencyKey: `active-seats:${customerId}:${snapshotId}`,
  timestamp: snapshotTimestamp,
  properties: { activeSeats }
});

if (error) throw new Error(error.message);

Capture the value and timestamp together. Persist the event and its idempotency key until delivery succeeds. Reuse them on retry; use a new key for a new snapshot. A periodic snapshot can miss a peak between samples. Choose a reporting interval that fits the billing rule, or send a snapshot when the resource count changes. Enforce immediate resource-count limits in your application transaction; a delayed snapshot cannot prevent concurrent writes.

One-time allowances

For an allowance that must not reset, configure a one-time entitlement or grant window. A non-expiring grant alone is not enough if it still has a recurring reset cadence. Keep the meter on the usage feature and make the allowance’s reset rule explicit. Read Entitlements for access rules and Choose the runtime call for complete request-path examples.

Features

Concepts

Events, meters, and features

Aggregation methods

Quota resets and billing periods

Report usage or authorize work

Report resource snapshots

One-time allowances

​Events, meters, and features

​Aggregation methods

​Quota resets and billing periods

​Report usage or authorize work

​Report resource snapshots

​One-time allowances

Events, meters, and features

Aggregation methods

Quota resets and billing periods

Report usage or authorize work

Report resource snapshots

One-time allowances