Skip to main content
Auto top-ups automatically purchase additional balance for a customer when their usage drops below a configured threshold. This prevents service interruptions for customers who don’t want to manually manage their balance.
Example
A customer on the Standard plan gets 5,000 credits per month. When their balance drops below 500, Autumn automatically purchases 1,000 more credits at $10 using the plan’s one-off prepaid price.

​
Prerequisites

Auto top-ups require:
  1. A plan with a one-off prepaid item for the feature you want to auto top-up
  2. The customer must have a saved payment method on file

​
Setting up

Auto top-ups are configured per customer, not in autumn.config.ts. Your plan needs a one-off prepaid item for the feature you want to auto top-up:
autumn.config.ts
import { feature, item, plan } from 'atmn';

export const credits = feature({
  id: 'credits',
  name: 'Credits',
  type: 'metered',
  consumable: true,
});

export const standard = plan({
  id: 'standard',
  name: 'Standard',
  price: { amount: 50, interval: 'month' },
  items: [
    item({
      featureId: credits.id,
      included: 5000,
      reset: { interval: 'month' },
    }),
    item({
      featureId: credits.id,
      price: {
        amount: 10,
        billingUnits: 1000,
        interval: 'one_off',
        billingMethod: 'prepaid',
      },
    }),
  ],
});
The one-off prepaid item ($10 per 1,000 credits) is what Autumn uses to replenish the balance. Configure auto top-ups per customer via the API (see below).

​
Configuring auto top-ups via API

Set up auto top-ups for a customer by updating their billing controls: 
import { Autumn } from "autumn-js";

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

await autumn.customers.update({
  customerId: "user_123",
  billingControls: {
    autoTopups: [{
      featureId: "credits",
      enabled: true,
      threshold: 500,
      quantity: 1000,
    }],
  },
});

​
Auto top-up configuration

FieldTypeDescription
feature_idstringThe feature to monitor
enabledbooleanWhether auto top-up is active
thresholdnumberBalance level that triggers a top-up
quantitynumberHow many units to purchase each time
purchase_limitobjectOptional limit on how often top-ups can occur

​
Purchase limits

To prevent runaway spending, you can set a purchase limit: 
{
  "purchase_limit": {
    "interval": "month",
    "interval_count": 1,
    "limit": 5
  }
}
This limits the customer to 5 auto top-ups per month. Supported intervals: hour, day, week, month.

​
How it works

  1. After every usage event (via track), Autumn checks the customer’s remaining balance
  2. If the balance falls below the configured threshold, an auto top-up is triggered
  3. Autumn creates an invoice for the configured quantity using the one-off prepaid price from the customer’s plan
  4. The invoice is charged to the customer’s saved payment method
  5. The balance is replenished with the purchased amount
Auto top-ups use burst suppression to prevent duplicate purchases when multiple track events happen in quick succession. There’s a 30-second cooldown between top-ups for the same feature.