Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
Payment Records
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

Create a usage record 

Billing
Usage Records
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 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. 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. For finer granularity, you can configure metered billing to have a tiered pricing model.

Parameters

  • quantityintegerRequired

    The usage quantity for the specified timestamp.

  • actionenum

    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, increment is the only allowed value.

  • timestampstring | timestamp

    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.

Returns

Returns the usage record object.

POST /v1/subscription_items/:id/usage_records
curl https://api.stripe.com/v1/subscription_items/si_IutmSSymhsWA5i/usage_records \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d quantity=100 \
  -d timestamp=1571252444
Response
{
  "id": "mbur_1IJ3zE2eZvKYlo2CsJAtf1Jl",
  "object": "usage_record",
  "livemode": false,
  "quantity": 100,
  "subscription_item": "si_IutmSSymhsWA5i",
  "timestamp": 1571252444
}