Stripe Billing Meter

Sum, count and last are three different bills from the same events

Stripe supports three aggregation formulas, and the difference between them is the difference between revenue figures rather than a technical preference.

**Sum** bills "based on the sum of all usage values for the billing period". **Count** bills "based on the count of all usage for the billing period". **Last** bills "based on the most recent usage event’s value for the billing period".

Run one month of events through each. A customer reports usage forty times, with values that add to 9,000 and a final reading of 300. Under sum the billable quantity is 9,000. Under count it is 40. Under last it is 300. The event stream is identical in all three cases.

The choice usually encodes a real commercial model. Sum fits consumption that accumulates, such as tokens processed or gigabytes transferred. Count fits per-action pricing where the size of each action does not matter. Last fits a subscription priced on a level rather than a flow, such as seats provisioned or storage held, where you are billing for the state at the end of the period rather than everything that happened during it.

The failure mode is a model change that never reaches the meter. A business that moves from per-request pricing to per-token pricing has changed from count to sum, and if the meter still counts events, the invoice is wrong in a way that looks like a pricing bug and is actually an aggregation setting.

The configuration is frozen once the meter exists

This is the constraint that makes the rest of the page consequential, and Stripe states it without qualification: "After you configure the meter, you can’t make any changes aside from the display name."

The aggregation formula, the event name, the payload keys and the ingestion mode are all set at creation and permanent thereafter. A meter created with the wrong formula cannot be corrected. The remedy is a new meter, a new event name, a price pointed at it, and a migration of every subscription using the old one.

Two details make that migration more awkward than it first sounds. Event names are exclusive: "You can only use an event name with a single meter", so the replacement meter cannot quietly adopt the name your application already sends. And a meter deactivated to stop the confusion goes to inactive status, where Stripe states "No more events for this meter will be accepted" and the meter "cannot be attached to a price", so the old and new meters have to coexist through the transition.

For the books, the practical consequence is that a metered price is not a setting anyone can adjust mid-period to fix a billing complaint. If a customer is being billed on the wrong basis, the correction is a credit note against the invoice that was issued, not an edit to the mechanism that issued it.

Raw or pre-aggregated, and the events that overwrite each other

A second permanent choice decides whether two events for the same moment both count.

Under **raw** ingestion, the default, Stripe handles "all meter events as standalone events. Multiple events sent for the same timestamp don’t overwrite each other. The aggregation includes the multiple events."

Under **pre-aggregated** ingestion, set to hourly or daily buckets, "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."

The overwrite behaviour is deliberate and useful, because it makes a retry idempotent: an application that resends a daily total after a network failure does not double-bill. It is also the source of a quiet undercount when the mode does not match how the application actually reports. A system sending genuine incremental usage several times an hour into a meter configured for hourly pre-aggregation keeps only the last of each hour and silently discards the rest.

The UTC detail is worth holding onto for period-end work. Bucket boundaries follow UTC regardless of where the business or its customers sit, so an hourly meter’s last event of a day is decided by UTC midnight and not by local close.

Correcting usage has a 24-hour window, and finalization closes it

Stripe provides a meter event adjustment to cancel incorrectly recorded events, and it is bounded in a way that matters for month-end.

"You can only cancel events sent to Stripe within the last 24 hours." Beyond that, the events stand.

And the harder limit: "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."

So once the invoice is finalized, the usage behind it is settled as far as Stripe is concerned, and any correction becomes an accounting exercise rather than a billing one. In practice that means a [credit note](/glossary/stripe-credit-note) against the issued invoice, which is the instrument built for reducing something already recorded.

There is a second correction route with its own quirk. You can record negative quantities to offset bad data, but "if the overall cycle usage is negative, Stripe reports the invoice line item usage quantity as 0". A correction larger than the usage it corrects does not produce a negative line. It produces a zero, and the excess simply disappears rather than carrying anywhere.

One more timing note that causes false alarms rather than errors: "Stripe processes meter events asynchronously, so aggregated usage in meter event summaries and on upcoming invoices might not immediately reflect recently received meter events." An upcoming invoice checked immediately after a usage push can legitimately look short.

What the meter looks like as an object

The meter itself is small, which is part of why it gets overlooked.

**Display name** is "The meter’s name", capped at 250 characters, and Stripe notes it is "Not visible to the customer". It is the only field that can be edited later. **Event name** is "The name of the meter event to record usage for", capped at 100 characters, and is what your application sends with each event so the right meter picks it up.

**Default aggregation** carries the formula. **Value settings** and **customer mapping** are the payload key overrides: value settings names "the key in the event payload that refers to the numerical usage value", defaulting to `value`, and customer mapping names "the key in the event payload that refers to the Customer ID", defaulting to `stripe_customer_id`.

**Event time window** is the raw or pre-aggregated choice, null for raw and otherwise `day` or `hour`. **Status** is active or inactive, with the deactivation timestamp recorded in status transitions.

The customer mapping field is the one worth checking when usage lands on nobody. If an application sends its own internal identifier under a key the meter is not looking for, the events are accepted and attach to no customer, so the invoice is short and nothing errors.