> ## Documentation Index
> Fetch the complete documentation index at: https://docs.integrateledger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overage

> Let customers on a paid plan keep working past their allowance, billed on their next invoice, up to a monthly cap.

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:

```ts ledger.config.ts theme={"system"}
plan({
	id: "scale",
	name: "Scale",
	monthlyCredits: 5000,
	monthlyPriceCents: 5000,
	overageUnitAmountCents: 1,
	overageBillingUnits: 1,
	overageCapCents: 2000,
}),
```

```json ledger.catalog.json theme={"system"}
{
  "id": "scale", "name": "Scale", "monthlyCredits": 5000, "monthlyPriceCents": 5000,
  "overageUnitAmountCents": 1, "overageBillingUnits": 1, "overageCapCents": 2000
}
```

Adding overage to an existing plan is a new [plan version](https://docs.integrateledger.com/configure-pricing/plans.md#change-a-plan): 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:

```json Response theme={"system"}
{
  "allowed": true,
  "availableCredits": 0,
  "chargedCredits": 2500,
  "overageCredits": 1500,
  "overageRemainingCents": 500,
  "request_id": "render_0003",
  "idempotent": false
}
```

`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`.

```typescript TypeScript theme={"system"}
await billing.setCustomerOverageCap({ customerId, body: { capCents: 5000 } });

// $0.01 per 2 credits for this customer on Scale.
await billing.setCustomerOverageOverride({
	customerId,
	body: { planId: "scale", unitAmountCents: 1, billingUnits: 2 },
});
```

```python Python theme={"system"}
billing.set_customer_overage_cap(customer_id=customer_id, cap_cents=5000)

# $0.01 per 2 credits for this customer on Scale.
billing.set_customer_overage_override(
    customer_id=customer_id, plan_id="scale", unit_amount_cents=1, billing_units=2
)
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.