Skip to main content
Rollovers let unused feature balances carry forward to the next billing cycle instead of being lost at reset. This gives customers more flexibility and prevents wasted allocation.
Example
A customer on a plan with 1,000 credits/month only uses 600 in January. With rollovers enabled, the remaining 400 credits carry over — giving them 1,400 credits available in February.

​
Setting up

Add a rollover config to a plan item:
autumn.config.ts
import { feature, item, plan } from 'atmn';

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

export const pro = plan({
  id: 'pro',
  name: 'Pro',
  price: { amount: 20, interval: 'month' },
  items: [
    item({
      featureId: credits.id,
      included: 1000,
      reset: { interval: 'month' },
      rollover: {
        max: 2000,
        expiryDurationType: 'forever',
        expiryDurationLength: 1,
      },
    }),
  ],
});
Push changes with atmn push.

​
Rollover configuration

FieldDescription
maxMaximum amount that can roll over. Set to null for no cap.
expiryDurationType"forever" (never expires) or "month" (expires after N months)
expiryDurationLengthNumber of months until rollover balances expire. Ignored if type is "forever".

​
How rollovers work

At the end of each billing cycle, when a feature’s balance resets:
  1. Autumn checks how much unused balance remains
  2. If rollovers are configured, the unused balance is saved as a rollover balance
  3. The feature resets to its granted amount, and the rollover is added on top
  4. If a max cap is set, the oldest rollover balances are trimmed first (FIFO)
  5. Expired rollover balances are removed automatically

​
Viewing rollover balances

Rollover balances appear in the breakdown array when you retrieve a customer’s balances. Each rollover entry has its own expiry date:

​
Deduction order

Rollover balances are treated as one_off (lifetime) balances. Because Autumn’s deduction order uses shorter intervals first, monthly balances are consumed before rollover balances — ensuring that new allocation is used before carried-over amounts.
Rollovers are only available on consumable features with a reset interval. Non-consumable features (like seats) don’t reset and therefore don’t support rollovers.

​
Entity rollovers

If you’re using sub-entity balances, rollovers are tracked per entity. Each entity’s unused balance rolls over independently.