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

​
Usage Alerts

Usage alerts send a webhook when a customer’s usage crosses a threshold you define. You can use this to take an action like sending a warning email, prompting an upgrade, or flagging the account internally.

​
Configuring usage alerts

Usage alerts are set per-customer (or per-entity) via the API, using the same billingControls field as spend limits. There are two threshold types:
  • usage — fires when absolute usage reaches a specific count
  • usage_percentage — fires when usage reaches a percentage of the included allowance
import { Autumn } from "autumn-js";

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

await autumn.customers.update({
  customerId: "user_123",
  billingControls: {
    usageAlerts: [{
      featureId: "api_calls",
      threshold: 800,
      thresholdType: "usage",
      enabled: true,
      name: "Approaching limit",
    }],
  },
});
For a percentage-based alert, use threshold_type: "usage_percentage" with a value between 0 and 100: 
await autumn.customers.update({
  customerId: "user_123",
  billingControls: {
    usageAlerts: [{
      featureId: "api_calls",
      threshold: 80,
      thresholdType: "usage_percentage",
      enabled: true,
      name: "80% usage warning",
    }],
  },
});
The usage_percentage threshold is calculated against the included allowance only. If the customer has overage enabled with a spend limit or max purchase, the percentage still refers to the included balance — not the total available usage.

​
Usage alert fields

FieldTypeDescription
feature_idstring (optional)The feature to monitor. If omitted, applies to all features.
thresholdnumberThe value that triggers the alert. Absolute count for usage, percentage (0-100) for usage_percentage.
threshold_typestring"usage" for an absolute count, "usage_percentage" for a percentage of the included allowance.
enabledbooleanWhether the alert is active. Defaults to true.
namestring (optional)A label to distinguish multiple alerts on the same feature.

​
How usage alerts work

  1. On each track call, Autumn compares the customer’s old and new usage against each enabled alert
  2. If the usage crosses the threshold (old usage was below, new usage is at or above), Autumn fires a balances.usage_alert_triggered webhook
  3. The alert fires once per threshold crossing — it won’t re-fire on subsequent track calls unless usage drops below the threshold and crosses it again
Alerts also work at the entity level. If you configure alerts on an entity, they fire based on that entity’s usage independently.
See the balances.usage_alert_triggered webhook schema for the full payload reference.

​
Multiple usage alerts

You can configure multiple alerts on the same feature or across different features. Each alert fires independently when its threshold is crossed. 
await autumn.customers.update({
  customerId: "user_123",
  billingControls: {
    usageAlerts: [
      {
        featureId: "api_calls",
        threshold: 500,
        thresholdType: "usage",
        enabled: true,
        name: "500 calls used",
      },
      {
        featureId: "api_calls",
        threshold: 90,
        thresholdType: "usage_percentage",
        enabled: true,
        name: "90% allowance used",
      },
    ],
  },
});
In this example, the customer will receive two separate webhook events as they use their API calls: one when they hit 500 absolute calls, and another when they reach 90% of their included allowance.