Guide

Prepaid commits on Stripe: what billing credits do, and what you still build

Stripe's billing credits can fund a prepaid commit. They don't roll over, cap rollover or bill a shortfall, and they count dollars rather than units. That last point cost $400 in one month of our worked example.

TrueUpp Research · Published 19 October 2026 · 6 min read

About this guide. It's based on Stripe's public documentation as we read it on 19 October 2026, with links to each page below. Stripe changes quickly, so check the current docs before you build. The worked example is an illustration, not any company's real figures. We're not affiliated with Stripe.

What billing credits are

A credit grant gives a customer a monetary balance that Stripe applies to their usage charges. The rules that matter for a commit:

• Metered prices only. Grants apply to subscription items on metered prices that report usage through Meters. They don't apply to licensed prices, one-off invoices, one-time items such as setup fees, or usage reported through the legacy Usage Records API.
• Money, not units. The grant amount is monetary. A grant of $10,000 covers $10,000 of priced usage, whatever the units cost.
• Applied at finalization. Credits apply when the invoice finalizes, after discounts and before tax. Usage is reconciled only at invoice time, so a customer can use more than their balance during the cycle.
• Eligibility is by the invoice's period end. A grant can apply when the invoice's period_end is on or after the grant's effective_at and before its expires_at. Credits never expire unless you set expires_at.
• Order when several grants apply: lowest priority number first, then the earliest expiry, then promotional before paid, then the earliest effective date, then the earliest created.
• Corrections. Voiding an invoice puts its credits back on the grant (or expires them straight away, if the grant has expired). A credit note doesn't: to restore credits after a credit note, you create a new grant.
• Limit. A customer can hold up to 100 unused grants at a time.

What they don't do

• No rollover. A grant can have an expiry date, but it has no setting to carry part of its balance into the next period, and no rollover cap.
• No minimums or shortfalls. Nothing in billing credits bills the gap when usage falls short of a commitment.
• No commit object. Stripe's own comparison of its basic usage-based billing with Metronome marks "prepaid credits and drawdown" and "enterprise contracts, commits, minimums" as Metronome features, not basic ones. Stripe completed its acquisition of Metronome in January 2026 and now calls it "Stripe's primary usage-based billing platform and the recommended starting point for all new integrations". Existing basic integrations remain fully supported.

So a team that already bills on Stripe and sells prepaid commits has two routes: move contract billing to Metronome, or keep Stripe and build the commit logic next to it. The Stripe practitioners who described their setups in public discussions this month had taken the second route: scheduled jobs and a small database table next to Stripe. The rest of this guide is for teams on that route.

A sturdier way to run it

1. Keep the drawdown ledger in units, outside Stripe. Rollover, caps, expiry and overage are worked out from the meter's usage and the contract terms, with each rolled lot carrying its own expiry date.
2. Send Stripe only what to bill. Post overage as its own line (a per-unit overage price, or an invoice item with the quantity and rate), and the prepaid fee as a licensed price. Grants aren't needed for the commit at all. Keep them for promotional credits, where dollars are the natural unit.
3. If you do use grants for the commit, derive each rollover grant from the unit ledger, never from the grant's leftover balance. Scope every grant to the contract's metered price, so another subscription's invoice on a different price can't use it first. Stripe applies a grant to whichever eligible invoice finalizes first.
4. Mind the date boundaries. Eligibility is checked against the invoice's period_end, not the moment it finalizes. Set expires_at after the end of the period the grant funds, and check that a grant becoming effective at the start of a period can't be picked up by the previous period's invoice. Run the boundaries through a test clock before going live.
5. Record which grant funded which period against the contract, so an auditor or the customer can trace every credit applied.

Other things to plan for

• Shortfalls. Bill them as a one-off invoice item with the calculation in the description. Grants won't touch it. See minimum commitment shortfall true-ups.
• Credit notes. Crediting an invoice that used grant credits doesn't give the credits back. If the contract says the customer keeps them, create a new grant and note why.
• Upgrades and downgrades. Stripe doesn't prorate usage-based billing, and a grant scoped to the old price won't apply to the new one. Decide what carries over from the contract's wording, then create the grants to match. See amendments as new segments.
• Annual overage tiers. Stripe works out tiered prices on each billing period's usage, so tiers reset every period unless you supply the position. See monthly vs annual tiers.
• Duplicate and late events. Meter events carry an identifier that Stripe keeps unique for at least 24 hours, and a timestamp that must be within the past 35 days. Retries arriving outside those windows need handling upstream. See what counts as usage.

Sources (Stripe documentation, read 19 October 2026): Billing credits · Create a credit grant · Compare basic usage-based billing and Metronome · Stripe completes Metronome acquisition · Prorations · Tiered pricing · Create a meter event