Record usage for billing

Learn how to record customer usage data.

Throughout each billing period, you must record usage in Stripe to bill your customers the correct amounts. You can decide how often you record usage in Stripe.

To record usage in Stripe, first configure your meter and then add the recorded usage through the Stripe Dashboard or API.

Configure your meter

Before you can record customer usage, you must configure your meter. After you configure the meter, you can’t make any changes aside from the display name.

Meter attribute	Description
Event name	The name of the meter event that you want to record usage for with the meter. When you send usage to Stripe, specify this event name in the `event_name` field for the meter event. This allows the correct meter to record and aggregate the usage. You can only use an event name with a single meter.
Event ingestion	Specify how to send events to Stripe: Raw: Handle all meter events as standalone events. Multiple events sent for the same timestamp don’t overwrite each other. The aggregation includes the multiple events. This is the default option if you don’t specify anything. Pre-aggregated: If you send events for a specific time interval (hourly or daily), Stripe only uses the most recently received meter event in that time interval. A newer event sent within the same hourly or daily window overwrites the previous one. The meter event timestamp in UTC dictates the hour and day boundaries.
Aggregation formula	Specify how to aggregate usage over the billing period: Sum: Bill customers based on the sum of all usage values for the billing period. Count: Bill customers based on the count of all usage for the billing period.
Payload key overrides	Specify which keys in the event payload refer to the customer and numerical usage values: value_settings: Use this parameter to define the key in the event payload that refers to the numerical usage value. The default key is `value`, but you can specify a different key, such as tokens. customer_mapping: Use this parameter to define the key in the event payload that refers to the Stripe customer ID. The default key is `stripe_customer_id`, but you can specify a different key, such as `customer_id`.

Record usage

Record usage in Stripe using the Dashboard or API.

Stripe processes meter events asynchronously, so aggregated usage in meter event summaries and on upcoming invoices might not immediately reflect recently received meter events.

Using the API

Use the Stripe API to record customer usage data.

Using the Stripe Dashboard

Use the Dashboard to upload a CSV file with usage data.

Fix incorrect usage data

If you identify incorrectly recorded events in the current billing period, you can create a meter event adjustment to cancel those events. You must specify the meter event identifier.

You can only cancel events sent to Stripe within the last 24 hours. If you cancel usage that’s included on a finalized invoice, we won’t update the invoice or issue a corrected invoice for the canceled usage. We don’t support billing adjustments for canceled usage on a finalized invoice sent to a customer.

You can also fix incorrectly recorded usage data by recording negative quantities. If the overall cycle usage is negative, Stripe reports the invoice line item usage quantity as 0.