Record usage for billing
Learn how to record and report usage for your customers.
Note
We updated our usage-based billing process. For information on our previous guidance, refer to our legacy usage-based billing documentation.
Configuring Meter![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Make sure that you have properly configured your Meter before recording usage. Meters are immutable, with the exception of the display name.
Event name![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
This is the name of the meter event that you plan to record usage for with this meter. Use this name on the event_
field of the Meter Event when you send usage to Stripe. This makes sure that the usage is ingested and aggregated by the correct meter. You can only use an event name with a single meter.
Event ingestion![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Specify how you want to send events to Stripe. There are two options:
- Raw: Treat all meter events as standalone events. Multiple events sent for the same timestamp don’t overwrite each other and are included in the aggregation. This is the default option if nothing is specified.
- Pre-aggregated (hourly or daily): If you’re sending events pre-aggregated over a specific time interval, either hourly or daily, Stripe only uses the most recent meter event within the hourly or daily window for aggregation. A newer event sent within the same hourly or daily window overwrites the previous one.
Aggregation formula![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Specify how to aggregate the usage over the billing period. Options for that parameter include:
- Sum: Bill based on the sum of all usage values for the billing period.
- Count: Bill based on the count of all usage for the billing period.
- Last (coming soon): Bill based on the most recent usage record for the billing period. If no usage is reported, the bill is based on a usage quantity of 0.
- Max (coming soon): Bill based on the biggest value in the specified bucket of time (second, hour, day) within the billing period. For example, the max number of users who logged in during any day of the billing period, often referred to as “high watermark billing”
Payload key overrides![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Specify which keys in the event payload refer to the customer and numerical usage values.
- value_settings: Define the key that refers to the numerical usage value in the payload of the meter event with this parameter. While the default key is
value
, you can specify a different key, such as tokens. - customer_mapping: Define the key in the event payload that refers to the Stripe Customer ID with this parameter. Although the default key is
stripe_
, you can specify a different one, such ascustomer_ id customer_
.id
Event filtering Beta![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Event filtering allows you to define specific conditions under which meter events are included or discarded in the billing process. For example, you can filter out events where the API status code equals 500 so that these events aren’t billable. Click here if you’re interested in joining the beta.
Recording usage![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
You can share usage information with Stripe by creating meter events with a customer_
, a numerical value, and optionally a timestamp. How often you report usage is up to you. For example, you can send usage as it occurs or in batches (for example, every day). At the end of the billing period, Stripe automatically calculates the total price and invoices for all usage during the billing period.
To create Meter Events:
Idempotency![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Use idempotency keys to prevent reporting usage more than one time due to latency or other issues. Every meter event corresponds to an identifier that you can specify in your request (if you don’t specify it, we autogenerate one).
Event timestamps![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Make sure that the timestamp falls within the past 35 calendar days and isn’t more than 5 minutes in the future (the 5-minute window accounts for clock drift between your server and Stripe’s systems).
Usage values![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
The numerical usage value in the payload only accepts positive whole number values.
Interested in using decimal or negative values?
Contact us at usage-based-billing@stripe.com so we can understand your use case better.
Rate limits![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Be mindful of the rate limit. The Meter Events endpoint only allows 1000 calls per second per non-connect Stripe account in livemode, and one concurrent call per customer per meter. If your service might exceed this limit, you can “bundle” your product into amounts. For example, if you charge per 1000 requests, base your product on “per 1k transactions” and send 1 usage record every 1000 times.
Monitor for 429
status codes and implement a retry mechanism with an exponential backoff schedule to manage request volume.
Also, consider incorporating some randomness into the backoff schedule to avoid a thundering herd effect.
Note
If you’re a connect platform that is making requests on behalf of a connected account using the Stripe-Account
header, you’re subject to regular stripe rate limits, which is 100 operations per second.
Interested in higher rate limits?
You can report usage either by dropping it into an S3 bucket or through a bulk endpoint. Learn about recording usage for billing with the S3 connector. For a better understanding of your specific needs and to get early access, please contact us at usage-based-billing@stripe.com.
Best practices![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Usage data is crucial for accurate user billing. Make your system resilient to network failures. For example, use a reliable queue like Amazon SQS to push data to Stripe so you can retry if necessary.
Configurable grace period![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Use the Invoice finalization grace period feature to configure how long it takes for invoices to transition from a draft
to a finalized state. During the invoice finalization window, you can report usage data for the billing period. For example, you can use this window to add late arriving usage data or manually upload usage data.
The grace period only applies to invoices enabled for automatic collection. You can set a delay of up to 72 hours (3 days).
If you have questions or feedback about this feature, contact us at usage-based-billing@stripe.com.
Regional considerations
Invoice finalization requirements vary by region. Consult your legal advisor for advice specific to your business.
Configure the grace period![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
To configure the Invoice finalization grace period:
Go to the Invoice settings page.
Scroll down to the Invoice finalization grace period section.
In this section, you can see the configured finalization behavior. Stripe’s default finalization behavior is set to 1 hour for all invoices.
Adjust the default behavior![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
To change the default behavior for all invoices across your integration:
- Click the overflow menu () in the Account default row.
- Select a grace period.
Create a rule![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
To set the grace period for a specific set of invoices, you can create rules. The default behavior remains in place as a catch-all in case the conditions on your rule(s) are not met.
Common mistake
Don’t set the finalization period to be longer than your subscription periods. For example, if your subscription period is daily, don’t set a finalization period greater than or equal to 24 hours.
Create a rule for all subscription invoices![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
To set a specific finalization grace period on the invoices generated at the end of a subscription period:
- Select Add rule.
- Specify the Invoice finalization delay. This defines the duration between when the invoice is first created and when it’s finalized.
- In the Conditions dropdown, select Invoice is from a subscription cycle condition.
- Click Save.
All invoices with usage-based products![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
To modify the finalization grace period behavior specifically for usage-based products, select Has a metered price from the Conditions dropdown.
To only target usage-based, subscription cycling invoices, select both Has a metered price and Invoice is from a subscription cycle condition in that order. For example, you can add a rule that specifies that for usage-based products, invoices generated from subscriptions cycle should remain in draft
for 72 hours before being finalized.
Reorder rules![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
To change the order in which rules are applied, click Change Order.
You can’t reorder the default account behavior, which serves as a catch-all. It is always applied last.
Revert to default behavior![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
To revert to the default behavior, delete all other rules and set the Invoice finalization delay for the Account default to 1 hour.
Resolve finalization grace period for invoices with multiple products![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Stripe applies the more conservative finalization grace period if there are line items that satisfy more than one rule. For example, if an invoice contains one line item for a usage-based product (72 hours) and a simple subscription product (1 hour), the invoice is finalized after 72 hours.
Failing webhooks![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
If your webhooks don’t return a successful response to the invoice.
event, those invoices adhere to a 72 hours finalization grace period regardless of the configured setting.
Learn more about invoice finalization.
Add usage to invoices in draft state![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
To have more time to aggregate and add usage to your draft invoices, you can delay finalization.
You can only add usage to existing invoices if:
- The invoice is in a
draft
state. - The timestamp from the Meters request is within the subscription period of this invoice.
If the usage timestamp is for any time after the created time of the draft
invoice, the usage is appended to the next invoice.
Draft invoice limitation
Currently, usage does not immediately appear on the draft invoice. To verify whether usage has successfully been added, use the Meters API or the Meters page in the Dashboard.
Fix incorrect usage![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
You can cancel incorrectly reported events using the Meter Event Adjustments. You need an identifier of the meter event to cancel it.
Canceling meter events has the following limitations:
- You can only cancel events that have been sent to Stripe within the last 24 hours.
- We don’t support billing adjustments for canceled usage that we’ve already invoiced a customer for.
- If you cancel usage already included on a finalized invoice, we won’t update that invoice. Additionally, we won’t issue a new correction invoice for the canceled usage.