# PostSubscriptionItemsSubscriptionItemUsageRecords

From **Stripe API**.

`POST /v1/subscription_items/{subscription_item}/usage_records`

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

<p>Usage records provide <code>quantity</code> 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 <a href="https://stripe.com/docs/billing/subscriptions/metered-billing">metered billing</a> plan, Stripe helps you send accurate invoices to your customers.</p>

<p>The default calculation for usage is to add up all the <code>quantity</code> values of the usage records within a billing period. You can change this default behavior with the billing plan’s <code>aggregate_usage</code> <a href="/docs/api/plans/create#create_plan-aggregate_usage">parameter</a>. When there is more than one usage record with the same timestamp, Stripe adds the <code>quantity</code> values together. In most cases, this is the desired resolution, however, you can change this behavior with the <code>action</code> parameter.</p>

<p>The default pricing model for metered billing is <a href="/docs/api/plans/object#plan_object-billing_scheme">per-unit pricing</a>. For finer granularity, you can configure metered billing to have a <a href="https://stripe.com/docs/billing/subscriptions/tiers">tiered pricing</a> model.</p>

## Parameters

### `subscription_item`

- Location: path
- Required: true
- Type: `string`

## Request body

- Required: true
### `application/x-www-form-urlencoded`

- Type: `object`

```json
{"additionalProperties":false,"properties":{"action":{"description":"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://stripe.com/docs/api/subscriptions/object#subscription_object-billing_thresholds), `increment` is the only allowed value.","enum":["increment","set"],"type":"string"},"expand":{"description":"Specifies which fields in the response should be expanded.","items":{"maxLength":5000,"type":"string"},"type":"array"},"quantity":{"description":"The usage quantity for the specified timestamp.","type":"integer"},"timestamp":{"anyOf":[{"enum":["now"],"maxLength":5000,"type":"string"},{"type":"integer"}],"description":"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."}},"required":["quantity"],"type":"object"}
```

## Security

### `basicAuth`

- Type: `http`
- Request header: `Authorization`
- Scheme: `basic`
Send credentials in the `Authorization` request header using the `Basic` scheme.

Basic HTTP authentication. Allowed headers-- Authorization: Basic <api_key> | Authorization: Basic <base64 hash of `api_key:`>

### `bearerAuth`

- Type: `http`
- Request header: `Authorization`
- Scheme: `bearer`
- Bearer format: `auth-scheme`
Send the token in the `Authorization` request header using the `Bearer` scheme.

Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

## Responses

### `200`

Successful response.

### `application/json`

- Type: `object`

Usage records allow you to report customer usage and metrics to Stripe for
metered billing of subscription prices.

Related guide: [Metered Billing](https://stripe.com/docs/billing/subscriptions/metered-billing).

```json
{"description":"Usage records allow you to report customer usage and metrics to Stripe for\nmetered billing of subscription prices.\n\nRelated guide: [Metered Billing](https://stripe.com/docs/billing/subscriptions/metered-billing).","properties":{"id":{"description":"Unique identifier for the object.","maxLength":5000,"type":"string"},"livemode":{"description":"Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.","type":"boolean"},"object":{"description":"String representing the object's type. Objects of the same type share the same value.","enum":["usage_record"],"type":"string"},"quantity":{"description":"The usage quantity for the specified date.","type":"integer"},"subscription_item":{"description":"The ID of the subscription item this usage record contains data for.","maxLength":5000,"type":"string"},"timestamp":{"description":"The timestamp when this usage occurred.","format":"unix-time","type":"integer"}},"required":["id","livemode","object","quantity","subscription_item","timestamp"],"title":"UsageRecord","type":"object","x-expandableFields":[],"x-resourceId":"usage_record"}
```

### `default`

Error response.

### `application/json`

- Type: `object`

An error response from the Stripe API

```json
{"description":"An error response from the Stripe API","properties":{"error":{"$ref":"#/components/schemas/api_errors"}},"required":["error"],"type":"object"}
```

## Request examples

### cURL

```shell
curl --request POST \
  --url https://api.stripe.com/v1/subscription_items/{subscription_item}/usage_records \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data '{
  "action": "string",
  "expand": [
    "string"
  ],
  "quantity": 1,
  "timestamp": "string"
}'
```