Record usage for billing

Configuring Meter

Make sure that you properly configure your Meter before recording usage. Meters are immutable, with the exception of the display name.

Event name

This is the name of the meter event that you plan to record usage for with this meter. Use this name on the event_name 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

Specify how you want 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 and are included in the aggregation. This is the default option if you don’t specify anything.
• 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 recently received meter event. A newer event sent within the same hourly or daily window overwrites the previous one. The hour and day boundaries are based on the meter event timestamp in UTC.

Aggregation formula

Specify how to aggregate the usage over the billing period:

• 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: Bill based on the most recent usage record for the billing period. If you don’t report usage, the bill is based on a usage quantity of 0. Click here if you’re interested in gaining access to a future beta.
• Max: 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.” Click here if you’re interested in gaining access to a future beta.

Payload key overrides

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_customer_id, you can specify a different one, such as customer_id.

Event filtering Beta

You can define specific conditions to determine which meter events the billing process includes or discards through event filtering. For example, you can filter out events with a 500 API status code to ensure that these events aren’t billable.

Recording usage

Upload your usage data with one of the following methods.

Configurable grace period

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.

Configure the grace period

To configure the Invoice finalization grace period:

1. Go to the Invoice settings page.
2. 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

To change the default behavior for all invoices across your integration:

1. Click the overflow menu () in the Account default row.
2. Select a grace period.

Create a rule

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.

Create a rule for most subscription invoices

To set a specific finalization grace period on the invoices generated at the end of a subscription period:

1. Select Add rule.
2. Specify the Invoice finalization delay. This defines the duration between when the invoice is first created and when it’s finalized.
3. In the Conditions dropdown, select Invoice is from a subscription cycle condition.
4. Click Save.

All invoices with usage-based products

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

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

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

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

If your webhooks don’t return a successful response to the invoice.created 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

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.

Fix incorrect usage

You can cancel incorrectly reported events using the Meter Event Adjustments. You need an identifier of the meter event to cancel it.

curl https://api.stripe.com/v1/billing/meter_event_adjustments \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d type=cancel \
  -d event_name=alpaca_ai_tokens \
  -d "cancel[identifier]"={{METER_EVENT_IDENTIFIER}}

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.