# Create a usage record

Creates a usage record for a specified subscription item and date, and fills it with a quantity.

Usage records provide `quantity` information that Stripe uses to track how much a customer is using your service. With usage information and the pricing model set up by the [metered billing](https://stripe.com/docs/billing/subscriptions/metered-billing) plan, Stripe helps you send accurate invoices to your customers.

The default calculation for usage is to add up all the `quantity` values of the usage records within a billing period. You can change this default behavior with the billing plan’s `aggregate_usage` [parameter](https://docs.stripe.com/docs/api/plans/create.md#create_plan-aggregate_usage). When there is more than one usage record with the same timestamp, Stripe adds the `quantity` values together. In most cases, this is the desired resolution, however, you can change this behavior with the `action` parameter.

The default pricing model for metered billing is [per-unit pricing](https://docs.stripe.com/docs/api/plans/object.md#plan_object-billing_scheme). For finer granularity, you can configure metered billing to have a [tiered pricing](https://stripe.com/docs/billing/subscriptions/tiers) model.

## Returns

Returns the usage record object.

## Parameters

- `quantity` (integer, required)
  The usage quantity for the specified timestamp.

- `action` (enum, optional)
  Valid values are `increment` (default) or `set`. When using `increment` the specified `quantity` will be added to the usage at the specified timestamp. The `set` action will overwrite the usage quantity at that timestamp. If the subscription has [billing thresholds](https://docs.stripe.com/docs/api/subscriptions/object.md#subscription_object-billing_thresholds), `increment` is the only allowed value.

- `timestamp` (string | timestamp, optional)
  The timestamp for the usage event. This timestamp must be within the current billing period of the subscription of the provided `subscription_item`, and must not be in the future. When passing `"now"`, Stripe records usage for the current time. Default is `"now"` if a value is not provided.

```curl
curl https://api.stripe.com/v1/subscription_items/{{SUBSCRIPTION_ITEM_ID}}/usage_records \
  -u "<<YOUR_SECRET_KEY>>" \
  -d quantity=100 \
  -d timestamp=1571252444
```

### Response

```json
{
  "id": "mbur_1IJ3zE2eZvKYlo2CsJAtf1Jl",
  "object": "usage_record",
  "livemode": false,
  "quantity": 100,
  "subscription_item": "si_IutmSSymhsWA5i",
  "timestamp": 1571252444
}
```