Usage-Based Billing from Salesforce in Stripe: Custom Objects to Metered Invoices

Salesforce is the system of record for what a customer agreed to pay for usage. It is almost never the system of record for the usage itself. The allowance, the overage rate, the tiers, and the annual minimum are on the opportunity, the CPQ consumption schedule, or the signed order form. The usage is in a custom object someone loads monthly, in your product's event stream, or in the warehouse. Stripe sits at the end and bills whatever its meters receive. Usage-based billing from Salesforce in Stripe is the loop that connects the three.

This guide covers that loop for B2B contracts, where the hard part is not sending events to Stripe but enforcing what the contract allows. It assumes Stripe Billing meters; the mechanics of meters, metered prices, and billing credits are covered on the Stripe usage-based billing page and are not repeated here. Updated September 2026.

Quick answer

Each period: collect usage per account from wherever it lives, map the account to its Stripe customer and subscription, rate the usage against the contract terms held in Salesforce (allowance, overage rate, tiers, minimum), send only the billable quantity to Stripe as meter events or an invoice item, preview the invoice, approve, and write the billed usage back to the Salesforce account so sales sees consumption against commitment. Stripe's meters do the metering and invoicing; the contract logic has to live somewhere else, and that somewhere is the decision this guide is about.

Where usage lives, and where the contract lives

If the usage is a custom object in Salesforce, it is usually because someone exports it from the product monthly and loads it. That works at low volume and drifts at high volume. The loop should be able to read usage from Salesforce, from the product, or from the warehouse, and treat Salesforce as the contract source either way.

What Stripe needs: meters, meter events, metered prices

A Stripe meter defines an event name and an aggregation (sum, count, or last value). A metered price attaches the meter to a product with a unit amount or tiers. A subscription item on the customer's subscription carries the metered price. During the period, meter events arrive with the customer and a value; at period end Stripe totals them and invoices the result. Three properties of this design matter for contract billing:

• Stripe bills every unit it receives. Unless the allowance is modeled in the price (tiers) or covered by billing credits, the first unit is billable.
• Meter events are idempotent by identifier. Send the same identifier twice and Stripe records one event. Every loop should set it, from the usage record ID or a hash of account, period, and unit.
• Events must land before the invoice finalizes. Usage that arrives after finalization needs a separate invoice item or the next period's invoice, and someone has to notice.

Three ways to enforce an allowance and a minimum

Option A: model it in the Stripe price

A graduated-tier metered price with a zero-amount first tier up to 50,000 units and $0.002 per unit above enforces a monthly allowance inside Stripe. It handles the simple case well. It does not handle allowances that reset annually, allowances that differ per customer (each customer needs their own price), or minimums.

Option B: billing credits

Grant credits that cover the allowance or the prepaid commitment; Stripe draws them down against metered usage before charging. This models prepaid drawdown well. Annual minimums with a true-up at term end, and allowances written as "up to 50,000 a month, non-cumulative," still need logic outside Stripe. Check the current status of billing credits on the Stripe usage-based billing page before designing around them.

Option C: rate before the meter

Compute the billable quantity outside Stripe: usage minus allowance, tiers applied, minimum checked at term end. Send only the billable units to the meter, or create the overage as an invoice item with a clear description ("API calls over 50,000 included: 10,000 at $0.002"). The contract logic lives in one place, every customer can have different terms, and the invoice reads like the contract. This is what LedgerUp does, and it is the option that survives amendments and renewals.

The monthly loop, step by step

1. Close the period. Pick a cutoff (usually the subscription's billing date) and collect usage per account up to it, deduplicated by record or event ID.
2. Map accounts to customers. Resolve each Salesforce Account to its Stripe customer and the subscription item carrying the metered price. Flag accounts with no mapping before doing anything else.
3. Load the terms. Allowance, overage rate, tiers, and minimum for the period, including any amendment effective mid-period.
4. Rate. Compute billable units and amount per account. Hold the annual true-up until the term's last period.
5. Send to Stripe. Meter events with identifiers, or invoice items with descriptions, for the billable amount only.
6. Preview and approve. Pull the upcoming invoice preview per customer, compare with last period and with the contract, and have a human approve anything outside tolerance.
7. Invoice. Let the subscription invoice on its date with net terms and PO number applied.
8. Write back. Billed usage, overage amount, and remaining allowance or commitment to the Salesforce account. This is the field sales will use to open the expansion conversation.

Four architectures

Where the loop breaks

• Late usage. The product's export runs on the 3rd; the invoice finalized on the 1st. The overage goes on next month's invoice with a note, or on a separate invoice, and the write-back has to say which.
• Duplicate events. A re-run without identifiers doubles the invoice. Identifiers on every meter event, always.
• Unit mismatch. The contract says API calls; the product logs requests including retries. Agree the unit in the order form and rate on that unit.
• Amendments mid-period. The allowance went from 50,000 to 100,000 on the 15th. Rate the two halves separately or prorate the allowance, and say which in the invoice description.
• Minimums and credits confused. A $60,000 annual minimum is not the same as $60,000 of prepaid credits. The first is a true-up at term end; the second is drawdown. Model them differently and the invoices will read correctly.
• No write-back. Sales cannot see consumption, so expansions surface at renewal instead of in month eight. Write billed usage and remaining commitment to the account every period.

Frequently asked questions