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 has 500 credits. When their balance drops below 100, Autumn automatically purchases 500 more credits using their saved payment method.

​
Prerequisites

Auto top-ups require:
  1. A one-off prepaid plan (the top-up plan) that the customer has purchased at least once
  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. First, create a top-up plan:
autumn.config.ts
import { feature, item, plan } from 'atmn';

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

export const creditTopUp = plan({
  id: 'credit_top_up',
  name: 'Credit Top-Up',
  addOn: true,
  items: [
    item({
      featureId: credits.id,
      price: {
        amount: 10,
        billingUnits: 500,
        interval: 'one_off',
        billingMethod: 'prepaid',
      },
    }),
  ],
});
Then 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: 100,
      quantity: 500,
    }],
  },
});

​
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 existing prepaid top-up 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.