Rollovers

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

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,
      },
    }),
  ],
});

​

Rollover configuration

​

How rollovers work

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

{
  "balances": {
    "credits": {
      "included_usage": 1400,
      "balance": 1400,
      "usage": 0,
      "breakdown": [
        {
          "plan_id": "pro",
          "included_usage": 1000,
          "balance": 1000,
          "usage": 0,
          "interval": "month",
          "next_reset_at": 1745193600000
        },
        {
          "id": "roll_abc123",
          "included_usage": 400,
          "balance": 400,
          "usage": 0,
          "interval": "one_off",
          "expires_at": null
        }
      ]
    }
  }
}

​

Deduction order

Example
A customer has a 1,000 credits/month balance that just reset, plus a 400 credits rollover from last month. They use 300 credits.
Autumn deducts all 300 from the rollover, leaving 100 credits in rollover and the full 1,000 credits monthly untouched.

​

Entity rollovers