Skip to main content
Start selling

Set Up Usage-Based Billing with Prepaid Credits

With Freemius, you can easily sell AI credits or set up usage-based billing for other consumptive features in your SaaS product.

You can sell different subscription plans that provide a specific number of credits per month.

However, you may also want to sell credit top-ups through one-time purchases. This is where Freemius usage-based billing with prepaid credits comes in.

If you're building a SaaS product with a similar setup using Next.js, you can watch our video tutorial for a complete walkthrough. The code is also available in our GitHub repository.

Configuring Your Plans​

We will configure the plans using two strategies:

  1. A set of plans with subscription-only pricing. These plans provide continued access to your SaaS product's features and may optionally include recurring monthly credits (e.g., 100 credits per month).
  2. A dedicated plan for credit top-ups. We will configure this plan with multi-unit pricing so that users can purchase different quantities of credits.

If you do not wish to have subscription plans, you can skip the first step and just set up the credit top-up plan.

Subscription-Only Plans​

For each subscription plan, set only the annual and/or monthly price under Billing Cycles.

To avoid confusion, ensure that these plans do not have a One-off Price.

Credit Top-Up Plan​

Create a new plan named Credit Topup. Under the plan's pricing, click Add Bulk to set prices for bulk credits.

In the example below, we have set the price for 1,000 credits as $8, 5,000 credits as $30, and 10,000 credits as $50.

After you set multi-unit pricing, the plan UI changes from Billing Cycles to unit-based pricing. The plan is now a multi-unit plan, allowing users to purchase different quantities of credits. For each pricing option, set only the One-off Price and leave the monthly and annual prices empty.

Configure Unit Label

By default, the unit label is set to Unit. You can change it to Credit or another label that makes sense for your SaaS product by following our guide.

Modify the Entitlement Logic​

In our basic SaaS Integration guide, we explained how to set up the purchase data processing logic for active subscriptions.

We will use the same database table and logic to maintain the user's credit balance.

Assume that the user's current balance is stored in a credits column in the users table. After the user makes a purchase, you can update their credit balance from the same function:

src/user-entitlement.ts
import { type PurchaseInfo } from '@freemius/sdk';
import { db } from './db'; // our database instance

// A map of pricing id with the number of credits it represents
const pricingToResourceMap: Record<string, keyof typeof resourceRecord> = {
  // The pricing ids are generated by Freemius and you can either put them here or in your .env file.
  [process.env.FREEMIUS_PRICING_ID_TOPUP_1000!]: 1000,
  [process.env.FREEMIUS_PRICING_ID_TOPUP_5000!]: 5000,
  [process.env.FREEMIUS_PRICING_ID_TOPUP_10000!]: 10000,
};

// A new function add credits

export async function addCredits(
  userId: string,
  credits: number
): Promise<void> {
  await db.user.update({
    where: { id: userId },
    data: { credit: { increment: credits } },
  });
}

export async function processPurchaseInfo(purchase: PurchaseInfo) {
  const user = await findUserByEmail(purchase.email);

  // We exit if the user hasn't registered to our application yet.
  // Alternatively, you can register the user automatically here if desired.
  if (!user) {
    return;
  }

  // Convert the insertion into a transaction to find out if the entitlement already exists
  await db.transaction(async (tx) => {
    const isExisting = await tx.userFsEntitlement.findUnique({
      where: {
        fsLicenseId: purchase.licenseId,
      },
    });

    if (isExisting) {
      // Just update the existing entitlement record with the new purchase info
      await tx.userFsEntitlement.update({
        where: {
          fsLicenseId: purchase.licenseId,
        },
        data: purchase.toEntitlementRecord(),
      });
    } else {
      // New purchase, so add it and also update the user's credit balance based on the pricing id
      const creditsToAdd = pricingToResourceMap[purchase.pricingId];
      await addCredits(user.id, creditsToAdd);
    }
  });
}

The code above performs the following steps:

  1. Checks the user_fs_entitlement table to see if the purchase already exists.
  2. If it exists, it updates the existing record with the new purchase info.
  3. If it does not exist, the purchase has not been processed before, so it adds the record and updates the user's credit balance based on the purchase's pricing ID.

The pricing ID is mapped to the number of credits it represents in the pricingToResourceMap object. You can either hardcode the pricing IDs here or store them in your .env file.

Consuming Credits​

Credit consumption must be handled in your application logic. For example, if you have a metered feature that consumes credits, you can check the user's credit balance before allowing access to it. For this purpose, we recommend creating utility functions.

export async function getCredits(userId: string): Promise<number> {
  const user = await db.user.findUniqueOrThrow({ where: { id: userId } });
  return user.credit;
}

export async function hasCredits(
  userId: string,
  credits: number = 1
): Promise<boolean> {
  const creditsAvailable = await getCredits(userId);

  return creditsAvailable >= credits;
}

export async function deductCredits(
  userId: string,
  credits: number
): Promise<User | null> {
  const updatedUser = await db.user.update({
    where: { id: userId },
    data: { credit: { decrement: credits } },
  });

  return updatedUser;
}

You can call these functions in your API routes or backend logic to check whether the user has enough credits before allowing access to a metered feature, then deduct the credits after the feature is used.

UI for Purchasing Credits​

You can use our React Starter Kit to display the credit top-up plan in your SaaS application. The component will automatically determine which plan is a multi-unit plan and display the pricing accordingly.

Follow these steps:

  1. Set up the Checkout endpoint using our JavaScript SDK.
  2. Use the Topup component from the React Starter Kit to display the credit top-up plan in your SaaS application.

Alternatively, you can use our Checkout Integration guide to implement a custom checkout flow for purchasing credits.

On this page: