Usage Records
Report metered usage for a subscription item and retrieve period summaries.
A usage record reports the quantity consumed for a metered subscription item. VINR accumulates these records throughout the billing cycle and converts the total into a line item on the invoice when the period ends.
Illustrative content. Hand-authored to demonstrate the Standard/Advanced pattern; the production page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.
The usage record objectAsk
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier, e.g. ur_4Cw9pL. |
subscription_item | string | The si_ this record belongs to. |
quantity | integer | Units consumed (or set, depending on action). |
timestamp | timestamp | Unix timestamp the usage occurred. |
action | enum | increment (add to running total) or set (replace the running total). |
Create a usage recordAsk
Report usage for a metered subscription item. Use action=increment (the default) to add to the
running total, or action=set to replace it — useful when reporting a gauge-style metric like
active seats.
List usage record summariesAsk
Returns aggregated usage totals for each billing period. Each summary contains the period boundaries and the total usage VINR will bill at period end — not the individual records themselves.
Related eventsAsk
Usage records do not fire events directly. Usage is consumed when VINR finalizes the invoice at the
end of the billing period — listen to invoice.created and invoice.payment_succeeded /
invoice.payment_failed to track metered billing outcomes. See
Events.
