Skip to main content
Spend limits let you cap how much overage a customer (or entity) can accumulate on a usage-based feature. Without a spend limit, usage-based features allow unlimited overage — the customer is billed for whatever they use. With a spend limit, Autumn blocks usage once the overage reaches the configured cap.
Example
A customer is on a plan with 1,000 API calls included per month and $1 per 1,000 additional calls. You set a spend limit of 5,000 on the api_calls feature. The customer can use up to 6,000 total API calls (1,000 included + 5,000 overage), and is blocked after that.

​
Prerequisites

Spend limits apply to usage-based features — features with overage pricing that allow usage beyond the included amount. If a feature doesn’t allow overage, spend limits have no effect. You’ll need a plan with a usage-based price on the feature you want to cap:
autumn.config.ts
import { feature, item, plan } from 'atmn';

export const apiCalls = feature({
  id: 'api_calls',
  name: 'API Calls',
  type: 'metered',
  consumable: true,
});

export const pro = plan({
  id: 'pro',
  name: 'Pro',
  price: { amount: 20, interval: 'month' },
  items: [
    item({
      featureId: apiCalls.id,
      included: 1000,
      price: {
        amount: 1,
        interval: 'month',
        billingUnits: 1000,
        billingMethod: 'usage_based',
      },
    }),
  ],
});
Push changes with atmn push. Then configure spend limits per customer via the API (see below).

​
Configuring spend limits

Spend limits are set per-customer (or per-entity) via the API, not at the plan level. Update a customer’s billingControls to add spend limits: 
import { Autumn } from "autumn-js";

const autumn = new Autumn({ secretKey: "am_sk_..." });

await autumn.customers.update({
  customerId: "user_123",
  billingControls: {
    spendLimits: [{
      featureId: "api_calls",
      enabled: true,
      overageLimit: 5000,
    }],
  },
});

​
Spend limit fields

FieldTypeDescription
feature_idstringThe feature to apply the spend limit to
enabledbooleanWhether the spend limit is active
overage_limitnumberMaximum overage units allowed beyond the included amount
The overage_limit is measured in the same units as the feature’s balance — not in dollars. For example, if your feature is “API calls”, an overage_limit of 5,000 means 5,000 additional API calls beyond the included amount.

​
How it works

  1. The customer uses a usage-based feature and begins accumulating overage beyond their included amount
  2. On each check or track call, Autumn computes total overage across all of the customer’s usage-based entitlements for that feature
  3. If the total overage would exceed the overage_limit, Autumn blocks the usage — check returns allowed: false, and track will not deduct beyond the limit
Spend limits aggregate overage across all of the customer’s entitlements for a given feature. If a customer has the same feature on multiple plans (e.g., a base plan and an add-on), the total overage across both is compared against the spend limit.

​
Checking access with spend limits

When a spend limit is configured, the check endpoint accounts for it in the allowed response: 
const { data } = await autumn.check({
  customerId: "user_123",
  featureId: "api_calls",
});

if (!data.allowed) {
  // Customer has hit their spend limit
}

​
Entity-level spend limits

You can also set spend limits on individual entities (users, workspaces, etc.) under a customer. Entity-level spend limits override customer-level limits for that entity. 
await autumn.entities.update({
  customerId: "user_123",
  entityId: "workspace_a",
  billingControls: {
    spendLimits: [{
      featureId: "api_calls",
      enabled: true,
      overageLimit: 2000,
    }],
  },
});
This limits workspace_a to 2,000 overage API calls, regardless of the customer-level spend limit.

​
Disabling a spend limit

To remove a spend limit, set enabled to false or omit the overageLimit: 
await autumn.customers.update({
  customerId: "user_123",
  billingControls: {
    spendLimits: [{
      featureId: "api_calls",
      enabled: false,
    }],
  },
});

​
Interaction with max purchase (usage limits)

Plans can also have a max purchase limit (also called “usage limit”) set on a plan item. This is a per-entitlement cap configured in the plan editor or CLI, and applies globally to all customers on that plan. When both a spend limit and a max purchase are configured for the same feature, the spend limit takes precedence. The per-entitlement max purchase is not enforced while a spend limit is active.
Example
A plan item has a max purchase of 1,000 (so customers can use up to 1,000 overage units). But you set a customer-level spend limit of 5,000 on that feature. The customer can use up to 5,000 overage units — the spend limit overrides the plan-level max purchase for that customer.
This lets you use max purchase as a sensible default for all customers, then selectively raise (or lower) the cap for specific customers using spend limits.
If you set a spend limit higher than the plan’s max purchase, the customer will be able to exceed the plan-level limit. If you set it lower, the customer will be capped before hitting the plan-level limit. In either case, the spend limit is the one that’s enforced.

​
Spend limits vs max purchase

Spend LimitsMax Purchase
Configured onCustomer or entityPlan item (in the plan editor)
ScopeAggregated across all entitlements for a featurePer-entitlement
Set viaUpdate Customer / Update Entity APIDashboard or CLI when creating a plan
DynamicYes — can be changed at any time per-customerNo — applies to all customers on the plan
PrecedenceOverrides max purchase when setUsed as default when no spend limit is set
Use casePer-customer overage caps (e.g., enterprise spending controls)Global safety limits for a plan tier