Pay-as-you-go overages

Let free plan users optionally add a card to pay for usage overages instead of getting blocked

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

1. Create Feature

   Create a metered consumable feature called “notifications”.

2. 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.

3. 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

1. 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.

   React

   import { useCustomer } from "autumn-js/react";
   
   const App = () => {
     const { customer } = useCustomer();
   
     console.log("Autumn customer:", customer);
   
     return <h1>Welcome, {customer?.name || "user"}!</h1>;
   };
   
2. Check Access

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

   React

   import { useCustomer } from "autumn-js/react";
   
   export function SendNotification() {
     const { check } = useCustomer();
   
     const handleSendNotification = async () => {
       const { data } = await check({ featureId: "notifications" });
   
       if (!data?.allowed) {
         // User is over limit on Free plan
         // Prompt them to switch to Pay-as-you-go
         alert("You've run out of notifications. Add a payment method to continue.");
         return;
       }
   
       // Proceed with sending notification
     };
   }
   

   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.

3. Track Usage

   After sending a notification, track the usage.

   Node.js

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

   React

   import { useCustomer } from "autumn-js/react";
   
   export default function EnableOveragesButton() {
     const { attach } = useCustomer();
   
     return (
       <button
         onClick={async () => {
           const { data } = await attach({
             productId: "pay_as_you_go",
             setupPayment: true,
           });
   
           if (data?.url) {
             window.location.href = data.url;
           }
         }}
       >
         Enable Pay-as-you-go
       </button>
     );
   }
   

   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.

5. 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