Pay-as-you-go overages

Free plan users can optionally add a payment method so that if they exceed their included usage, they’re billed for the overage rather than blocked. This is done by having two plans: a Free plan (no overages) and a Pay-as-you-go plan (with overage pricing). This is useful when you want to:

Avoid blocking engaged free users who exceed limits
Convert free users to paying customers through natural usage growth
Offer a “soft limit” experience without requiring upfront payment

Example case

We have a product with the following pricing:

Free plan: 1,000 notifications per month included, blocked when exceeded
Pay-as-you-go plan: 1,000 notifications per month included, $1 per 1,000 notifications beyond the included amount

If a free user exceeds 1,000 notifications, they get blocked. If they’ve switched to Pay-as-you-go (by adding a card), they’re charged $1 per 1,000 notifications at the end of the billing period.

Configure Pricing

Create Feature

Create a metered consumable feature called “notifications”.

Create Free Plan

Create a free plan with 1,000 notifications included per month. Set auto-enable so new customers automatically start on this plan.

Create Pay-as-you-go Plan

Create a Pay-as-you-go plan with the same 1,000 notifications included, but with overage pricing:

Grant amount: 1,000 notifications
Price: $1 per 1,000 notifications per month
Billing method: Usage-based

In advanced, toggle off the “Reset usage when enabled” flag. This ensures that when a user switches from Free to Pay-as-you-go, their existing usage carries over instead of resetting to 0.

Implementation

Create an Autumn Customer

When your user signs up, create an Autumn customer. This will automatically assign them the Free plan with 1,000 included notifications.

import { Autumn } from "autumn-js";

const autumn = new Autumn({
  secretKey: 'am_sk_42424242',
});

const { data, error } = await autumn.customers.create({
  id: "user_123",
  name: "Jane Doe",
  email: "jane@example.com",
});

import asyncio
from autumn import Autumn

autumn = Autumn('am_sk_42424242')

async def main():
    customer = await autumn.customers.create(
        id="user_123",
        name="Jane Doe",
        email="jane@example.com",
    )

asyncio.run(main())

curl --request POST \
  --url https://api.useautumn.com/customers \
  --header 'Authorization: Bearer am_sk_42424242' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "user_123",
    "name": "Jane Doe",
    "email": "jane@example.com"
  }'

Check Access

Before sending a notification, check if the customer has remaining capacity.

import { Autumn } from "autumn-js";

const autumn = new Autumn({
  secretKey: 'am_sk_42424242',
});

const { data } = await autumn.check({
  customer_id: "user_123",
  feature_id: "notifications",
});

if (!data.allowed) {
  console.log("User is over limit on Free plan");
  // Prompt them to switch to Pay-as-you-go
}

import asyncio
from autumn import Autumn

autumn = Autumn("am_sk_42424242")

async def main():
    response = await autumn.check(
        customer_id="user_123",
        feature_id="notifications",
    )
    
    if not response.allowed:
        print("User is over limit on Free plan")
        # Prompt them to switch to Pay-as-you-go

asyncio.run(main())

curl -X POST "https://api.useautumn.com/v1/check" \
  -H "Authorization: Bearer am_sk_42424242" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "feature_id": "notifications"
  }'

Show check response (Free plan user)

{
  "allowed": true,
  "customer_id": "user_123",
  "feature_id": "notifications",
  "balance": 870,
  "usage": 130,
  "included_usage": 1000,
  "unlimited": false,
  "overage_allowed": false
}

When balance reaches 0 and overage_allowed is false, the user will be blocked.

Track Usage

After sending a notification, track the usage.

import { Autumn } from "autumn-js";

const autumn = new Autumn({
  secretKey: 'am_sk_42424242',
});

await autumn.track({
  customer_id: "user_123",
  feature_id: "notifications",
  value: 1,
});

import asyncio
from autumn import Autumn

autumn = Autumn("am_sk_42424242")

async def main():
    await autumn.track(
        customer_id="user_123",
        feature_id="notifications",
        value=1,
    )

asyncio.run(main())

curl -X POST "https://api.useautumn.com/v1/track" \
  -H "Authorization: Bearer am_sk_42424242" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "feature_id": "notifications",
    "value": 1
  }'

Switch to Pay-as-you-go

When the user is approaching or has exceeded their limit, prompt them to switch to the Pay-as-you-go plan. Use attach with setup_payment: true to collect their card without charging upfront.

You can retrieve the user’s notification balance from the check or customer method, and use this to conditionally prompt them to add a payment method.

import { Autumn } from "autumn-js";

const autumn = new Autumn({
  secretKey: 'am_sk_42424242',
});

const { data } = await autumn.attach({
  customer_id: "user_123",
  product_id: "pay_as_you_go",
  setup_payment: true,
  success_url: "https://your-app.com/settings",
});

if (data.url) {
  // Redirect user to Stripe setup page
}

import asyncio
from autumn import Autumn

autumn = Autumn("am_sk_42424242")

async def main():
    response = await autumn.attach(
        customer_id="user_123",
        product_id="pay_as_you_go",
        setup_payment=True,
        success_url="https://your-app.com/settings",
    )
    
    if response.url:
        # Redirect user to Stripe setup page
        pass

asyncio.run(main())

curl -X POST "https://api.useautumn.com/v1/attach" \
  -H "Authorization: Bearer am_sk_42424242" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "product_id": "pay_as_you_go",
    "setup_payment": true,
    "success_url": "https://your-app.com/settings"
  }'

Once the user completes the setup, they’ll be switched from the Free plan to the Pay-as-you-go plan. Because “Reset usage when enabled” is off, their existing usage carries over. Any usage beyond 1,000 notifications will be billed at the end of the billing period.

Overages are Now Enabled

After switching to Pay-as-you-go, the user’s check response will show overage_allowed: true. They can continue using the feature beyond their included limit.

Show check response (Pay-as-you-go user)

{
  "allowed": true,
  "customer_id": "user_123",
  "feature_id": "notifications",
  "balance": -200,
  "usage": 1200,
  "included_usage": 1000,
  "unlimited": false,
  "overage_allowed": true
}

The user has sent 1,200 notifications (200 over the limit). They will be billed $0.20 at the end of the billing period.

Summary

Plan	Over Limit	Result
Free	No	✅ Allowed
Free	Yes	❌ Blocked
Pay-as-you-go	No	✅ Allowed
Pay-as-you-go	Yes	✅ Allowed, billed at end of period