# 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 object

| 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 record

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.

`POST /v1/subscription-items/{id}/usage-records`

```bash
curl -X POST https://api.vinr.com/v1/subscription-items/si_7Bm3qR/usage-records \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d quantity=150 \
-d timestamp=1716300000 \
-d action=increment
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const record = await vinr.subscriptionItems.createUsageRecord('si_7Bm3qR', {
quantity: 150,
timestamp: 1716300000,
action: 'increment',
});
```

```python
import vinr

record = vinr.SubscriptionItem.create_usage_record(
  "si_7Bm3qR",
  quantity=150,
  timestamp=1716300000,
  action="increment",
)
```

```ruby
record = Vinr::SubscriptionItem.create_usage_record(
'si_7Bm3qR',
quantity: 150,
timestamp: 1716300000,
action: 'increment',
)
```

```json
{
"id": "ur_4Cw9pL",
"subscription_item": "si_7Bm3qR",
"quantity": 150,
"timestamp": 1716300000,
"action": "increment"
}
```

## List usage record summaries

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.

`GET /v1/subscription-items/{id}/usage-record-summaries`

```bash
curl "https://api.vinr.com/v1/subscription-items/si_7Bm3qR/usage-record-summaries?limit=5" \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
const summaries = await vinr.subscriptionItems.listUsageRecordSummaries(
'si_7Bm3qR',
{ limit: 5 },
);
```

```python
summaries = vinr.SubscriptionItem.list_usage_record_summaries(
  "si_7Bm3qR",
  limit=5,
)
```

```ruby
summaries = Vinr::SubscriptionItem.list_usage_record_summaries(
'si_7Bm3qR',
{ limit: 5 },
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "urs_2Dp1nK",
    "subscription_item": "si_7Bm3qR",
    "period": {
      "start": 1716300000,
      "end": 1717200000
    },
    "total_usage": 4820
  }
],
"has_more": false
}
```

## Related events

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](/docs/api-reference/events).