billingControls field when updating a customer or updating an entity.
Overage Allowed
By default, whether a customer can use a feature beyond their included balance depends on the plan’s pricing model. Features with usage-based pricing (pay-per-use) automatically allow overage — the customer keeps using and gets billed for the extra. Features without usage-based pricing (like a flat included allowance) block usage once the balance hits zero. TheoverageAllowed control lets you override this default per customer or entity.
Default behavior (no override)
With overageAllowed enabled
Setting overageAllowed to true on a feature lets a customer consume beyond their included balance even when the plan doesn’t have usage-based pricing for that feature. The balance goes negative, meaning you can track how much overage occurred, though no automatic overage charge is created.
Example
A customer is on a free plan with 100 API calls included (no overage pricing). Normally they’d be blocked at 0 remaining. You setoverageAllowed: trueforapi_calls. Now they can keep using beyond 100, and you can decide how to handle the overage in your application (prompt an upgrade, bill manually, etc.).
Disabling overage on a pay-per-use feature
You can also useoverageAllowed to block overage on a feature that would normally allow it. Setting enabled: false forces a hard cap at the included balance — even if the plan has usage-based pricing for that feature.
Example
A customer’s plan includes 1,000 API calls with pay-per-use overage at $1/1,000 calls. You setoverageAllowed: falseforapi_calls. The customer is now blocked at 1,000 total calls — no overage charges will occur.
How it interacts with spend limits
overageAllowed and spend limits are complementary:
overageAllowedanswers: can usage go beyond the included balance?- Spend limits answer: how far can overage go?
overageAllowed is checked first. If overage is blocked (enabled: false), the spend limit is irrelevant. If overage is allowed, the spend limit caps how much overage can accumulate.
Spend Limits
Spend limits cap how much overage a customer can accumulate on a usage-based feature. Once the cap is reached,check returns allowed: false and track stops deducting.
Example
A customer’s plan includes 1,000 API calls with $1 per 1,000 overage calls. You set a spend limit of 5,000 onapi_calls. The customer can use up to 6,000 total calls (1,000 included + 5,000 overage), then they’re blocked.
The
overage_limit is measured in feature units, not dollars. An overage_limit of 5,000 on “API calls” means 5,000 additional API calls beyond the included allowance.Usage Limits
A usage limit is a windowed hard cap: at mostlimit units of a feature per interval window (day, week, month, or year), regardless of how much balance the customer has left or how the plan is priced. It’s a throttle, that you or your customer may set.
Once usage reaches the cap inside the active window, check returns allowed: false and track stops deducting.
Usage limits cap total usage of a feature within a period: a sub-limit within an existing balance. They sit on top of the plan’s allowance and apply even when there’s balance remaining and even when the feature has no overage pricing.
The consumed counter belongs to the window, not to the limit’s configuration — editing the limit never resets what’s already been counted. To unblock a capped customer mid-window: disable the limit (enabled: false) to stop it gating while keeping its configuration, raise the limit (headroom becomes the new limit minus usage already counted), or delete it.
Example
A customer’s plan includes 300 credits per month, but you want to stop any single day from burning through them. Set a usage limit of 50 oncreditswith adayinterval. The customer still gets their 300 monthly credits, but can never spend more than 50 in a day.
Each customer/entity feature in a
get response carries a usage_limits array where every entry also reports the usage consumed in the current window, so you can show “12 / 50 used today” without a separate call.
Window reset and plan changes
Each window aligns to the customer’s billing cycle, not the UTC calendar. Aday cap rolls at the customer’s billing time-of-day; a month cap rolls on their billing-cycle anchor. When there’s no billing cycle to anchor to (e.g. a feature with no backing plan), the window falls back to UTC calendar alignment — daily windows roll at UTC midnight, monthly on the 1st.
Because the window is tied to the feature’s reset cycle, a plan change that restarts that cycle also restarts the window. If a customer upgrades mid-month and their billing anchor moves, the usage limit’s window re-anchors to the new cycle and the consumed counter starts fresh.
Caps on credit systems
When a feature is part of a credit system, you can cap usage at either level:- Cap the credit balance — e.g. limit total
creditsspend per window across every feature that draws from it. - Cap an individual feature — e.g. give a credit system shared by features A, B, and C, but limit how many units of B specifically can be used per window. The per-feature cap is converted into credits using B’s credit cost, so both caps are enforced together.
Example — per-feature cap inside a credit systemWhen more than one cap applies to a check (the cap on the evaluated feature and a cap on its parent credit system), Autumn enforces the tightest one — the remaining headroom is the minimum across all armed caps.
Yourcreditssystem is spent byimages,transcriptions, andexports. Customers can spend credits freely across all three, but you capexportsat 10 per day so one feature can’t drain the whole balance. A check or track onexportsis blocked at 10/day even if plenty of credits remain.
Usage Alerts
Usage alerts fire a webhook when a customer’s usage crosses a threshold. They don’t block usage — they notify, so you can take action like sending a warning email or prompting an upgrade. There are two threshold types:usage— fires when absolute usage reaches a specific countusage_percentage— fires when usage reaches a percentage of the included allowance
Each alert fires once per threshold crossing. It won’t re-fire unless usage drops below the threshold and crosses it again.
When triggered, Autumn sends a
balances.usage_alert_triggered webhook. See the webhook schema for the full payload.
For more details and examples, see Spend Limits & Usage Alerts.
Auto Top-Ups
Auto top-ups automatically replenish a customer’s prepaid balance when it drops below a configured threshold. This prevents service interruptions for customers who don’t want to manually manage their credits.ExampleAuto top-ups require a plan with a one-off prepaid item for the feature, and the customer must have a payment method on file.
A customer gets 5,000 credits per month. When their balance drops below 500, Autumn automatically purchases 1,000 more credits using the plan’s one-off prepaid price.
To prevent runaway spending, you can set a purchase limit:
hour, day, week, month.
For setup instructions and how it works end-to-end, see Auto Top-Ups.
Customer vs Entity Controls
Billing controls can be set at two levels:
Entity-level controls are configured by updating the entity instead of the customer. Entity-level controls override customer-level controls for that entity — for example, an entity overage override takes precedence over the customer-level setting, and entity spend limits override the customer-level limit.
Overrides are resolved per feature: an entity’s own entry for a feature wins, and the customer’s entries fill in any features the entity doesn’t set. For usage limits specifically, an inherited (customer-level) cap counts usage against the shared customer window — it’s the same aggregate cap, not a separate per-entity copy. An entity-level usage limit, by contrast, gets its own per-entity window and counter.
Example — per-entity cap
An org (the customer) has 1,000 monthly API calls shared across its workspaces (entities). You set a customer-level usage limit of 1,000/month so the org can’t exceed its plan, and an entity-level limit of 200/day on a noisy workspace so it can’t starve the others. The workspace is blocked at 200/day; the org is blocked at 1,000/month.
Auto top-ups are customer-level only because they create invoices and charge a payment method, which is tied to the customer account — not individual entities.
Plan-Level Defaults
Every billing control can also be defined on a plan (in the dashboard under plan settings → billing controls, or via thebillingControls field when creating or updating a plan). Plan-level controls act as defaults for every customer on that plan — set a daily usage limit once on your free tier instead of on each customer.
Resolution when a customer is on one or more plans:
- A customer-level entry shadows the plan’s entry for the same feature (for usage limits, the same feature and conditions). Setting a control on the customer is how you override the plan default — and a disabled customer entry still shadows the plan’s, it doesn’t resurface it.
- With multiple attached plans defining the same control, the most restrictive wins (auto top-ups: the most recently attached plan’s config).
Reading effective controls
From API version2.3.0, fetching a customer returns the effective controls: plan defaults are merged into billing_controls, and every entry carries a source field so you can tell overrides from inherited defaults. Inherited usage limits include the live window usage, so you can render “X of 200 used today” without extra calls.
billing_controls contains only customer-level entries. Entity responses always show the entity’s own controls.
Related Webhooks
Billing controls tie into three webhook events that fire automatically based on usage:
For webhook setup and security details, see Webhooks.