Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs-v1.useautumn.com/llms.txt

Use this file to discover all available pages before exploring further.

If a user hits a usage limit you granted them, they may be willing to purchase a top-up. These are typically one-time purchases (but can also be recurring add-ons) that grant a fixed usage of a feature. This gives users full spend control and allows your business to be paid upfront. For these reasons, it tends to be a more popular alternative to usage-based pricing — eg, OpenAI uses this model for their API.

​
Example case

In this example, we have an AI chatbot that offers:
  • 10 messages per month for free
  • An option for customers to top-up messages in packages of $10 per 100 messages.

​
Configure Pricing

1

​
Create Features

Create a metered consumable feature for our messages, so we can track their balance.
2

​
Create Free and Top-up Plans

Free Plan
Create a free plan, and assign 10 messages to it. We’ll add an interval of “month”, so that the user is granted 10 periodically.
Make sure to set the auto-enable flag on the free plan, so that it is automatically assigned to new customers.
Top up Plan
Now we’ll create our top-up plan. Again, we’ll assign the messages feature, but this time with a prepaid price of $10 per 100 messages.Since these messages have interval “one-off”, the messages will last forever (unlike our Free plan messages, which reset every month).Features with a prepaid price require a quantity to be passed in when a customer purchases the plan, so the customer can specify how many messages they want to top up with.

​
Implementation

1

​
Create an Autumn Customer

When your user signs up, create an Autumn customer. This will automatically assign them the Free plan, and grant them the 10 monthly messages.
import { useCustomer } from "autumn-js/react";

const App = () => {
  const { customer } = useCustomer();

  console.log("Autumn customer:", customer);

  return <h1>Welcome, {customer?.name || "user"}!</h1>;
};
2

​
Checking for access

Before our user sends a message, we’ll first check if they have a balance of messages remaining.
import { useCustomer } from "autumn-js/react";

export function CheckPremiumMessage() {
  const { check, refetch } = useCustomer();

  const handleCheckAccess = async () => {
    const { data } = await check({ featureId: "messages" });

    if (!data?.allowed) {
      alert("You've run out of messages");
    } else {
      // proceed with sending message
      await refetch();
    }
  };
}
3

​
Tracking messages used

After the user has used a message, record it in Autumn to decrease their remaining balance. In this example, the user used 5 messages.
import { Autumn } from "autumn-js";

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

await autumn.track({
  customer_id: "user_or_org_id_from_auth",
  feature_id: "messages",
  value: 5,
});
4

​
Purchasing top-ups

When users run out of messages, they can purchase additional messages using our top-up plan. In this example, the user is purchasing 200 premium messages, which will cost them $20.
import { useCustomer, CheckoutDialog } from "autumn-js/react";

export default function TopUpButton() {
  const { checkout } = useCustomer();

  return (
    <button
      onClick={async () => {
        await checkout({
          productId: "top_up",
          dialog: CheckoutDialog,
          options: [{
            featureId: "messages",
            quantity: 200,
          }],
        });
      }}
    >
      Buy More Messages
    </button>
  );
}
Once the customer completes the payment, they will have an additional 200 premium messages available to use.
5

​
Displaying balances to the user

You can display to the user by getting balances from the customer method. Under the customer.features record, you’ll be able to retrieve a current balance, total granted, and a breakdown of their monthly vs top-up messages.
import { useCustomer } from "autumn-js/react";

const { customer } = useCustomer();

const messages = customer?.features?.messages;

// Get breakdown of monthly vs prepaid balances
const monthlyBalance = messages?.breakdown?.find(
  (b) => b.interval === "month"
);
const prepaidBalance = messages?.breakdown?.find(
  (b) => b.interval === "lifetime"
);

// Display both balances to the user
return (
  <div>
    <p>Monthly: {monthlyBalance?.balance ?? 0} remaining</p>
    <p>Prepaid: {prepaidBalance?.balance ?? 0} remaining</p>
    <p>Total: {messages?.balance ?? 0} messages available</p>
  </div>
);