Skip to main content
Without overage, a customer who runs out of credits is refused until their plan renews or they buy a pack. With overage, a paid plan keeps them working: Ledger records the extra credits, and Stripe bills them on the next renewal invoice, up to a monthly cap. Buyers see the terms before they pay. Stripe’s Checkout shows the plan’s price, and above its Subscribe button Ledger adds what the plan includes and how overage bills, with the customer’s own cap or negotiated rate when they have one: “Includes 1,000 credits each month. Unused credits don’t roll over. After that, extra credits are billed on your next invoice at $0.50 per 10 credits, rounded up to the next 10, up to $20.00 a month. Renews monthly until you cancel. Extra credits used before you cancel are billed on a final invoice.”

​
Add overage to a plan

Set overageUnitAmountCents, the price per overageBillingUnits credits (default 1), and optionally a default monthly cap, overageCapCents. Leave the cap out for no cap. This Scale plan charges $0.01 per extra credit, capped at $20 a month:
Adding overage to an existing plan is a new plan version: customers already on it keep their current terms.

​
How it’s decided

Your integration doesn’t change. Ledger spends plan credits, then packs, then overage. A use that costs more than what’s left spends the rest and records the remainder as overage, as long as the period’s overage cost stays within the cap. A use that would pass the cap is refused whole with 409 overage_cap_reached; one that lands exactly on it is allowed. check makes the same decision, so allowed: true can mean the use will be billed as overage. A customer with 1,000 credits left who tracks a 2,500-credit use gets:
Response
overageCredits is this period’s overage so far, and overageRemainingCents is what’s left under the cap ($20.00 − $15.00). The period’s cost is ceil(credits ÷ overageBillingUnits) × overageUnitAmountCents, worked out for each rate separately.

​
Per-customer caps and rates

A customer’s own cap replaces the plan default, higher or lower. 0 turns overage off for them and null restores the default. An override gives one customer a negotiated rate; the plan must already have overage terms, or it returns 409 plan_has_no_overage.
Both take effect on the next track. Leave out planId to apply an override to whichever overage plan the customer is on, so it carries across upgrades; a plan-specific override wins. Send unitAmountCents: null to clear it. The cap response’s overage.capSource says where the effective cap comes from: customer, override, plan, or null.

​
How it’s billed

Each renewal invoice gets one line per rate for the period that just ended, such as “Scale – overage, 1,500 credits”. After a plan change, the old plan’s overage bills at its own rate. When a subscription ends, Ledger bills any remaining overage on a final invoice. In the dashboard, a customer in overage shows In overage and a meter against their cap.