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

Usage Records

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

Related guide: Metered billing

This is our legacy usage-based billing API. See the updated usage-based billing docs.

Endpoints

The Usage Record object

Attributes

  • idstring

    Unique identifier for the object.

  • quantityinteger

    The usage quantity for the specified date.

  • subscription_itemstring

    The ID of the subscription item this usage record contains data for.

  • timestamptimestamp

    The timestamp when this usage occurred.

More attributes

  • objectstring

  • livemodeboolean

The Usage Record object
{
  "id": "mbur_1IJ3zE2eZvKYlo2CsJAtf1Jl",
  "object": "usage_record",
  "livemode": false,
  "quantity": 100,
  "subscription_item": "si_IutmSSymhsWA5i",
  "timestamp": 1571252444
}

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
}

List all subscription item period summaries

For the specified subscription item, returns a list of summary objects. Each object in the list provides usage information that’s been summarized from multiple usage records and over a subscription billing period (e.g., 15 usage records in the month of September).

The list is sorted in reverse-chronological order (newest first). The first list item represents the most current usage period that hasn’t ended yet. Since new usage records can still be added, the returned summary information for the subscription item’s ID should be seen as unstable until the subscription billing period ends.

Parameters

No parameters.

More parameters

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit summaries, starting after summary starting_after. Each entry in the array is a separate summary object. If no more summaries are available, the resulting array is empty.

GET /v1/subscription_items/:id/usage_record_summaries
curl -G https://api.stripe.com/v1/subscription_items/si_E9xjsAhGRXCCWe/usage_record_summaries \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d limit=3
Response
{
  "object": "list",
  "url": "/v1/subscription_items/si_E9xjsAhGRXCCWe/usage_record_summaries",
  "has_more": false,
  "data": [
    {
      "object": "list",
      "url": "/v1/subscription_items/si_E9xjsAhGRXCCWe/usage_record_summaries",
      "has_more": false,
      "data": [
        {
          "id": "sis_1Bnyrd2eZvKYlo2CuVcUbXln",
          "object": "usage_record_summary",
          "invoice": "in_1Bnyrd2eZvKYlo2CSV57GLV8",
          "livemode": false,
          "period": {
            "end": 0,
            "start": null
          },
          "subscription_item": "si_18UXa82eZvKYlo2CbYoIEZVv",
          "total_usage": 1
        }
      ]
    }
  ]
}