Credits

MkSaaS provides a flexible, modular credits system for rewarding users, enabling pay-per-use features, and supporting a variety of business models. This guide explains how to enable, configure, and use the credits system in your application.

Setup

To get started with the credits system, please follow the steps below to configure the necessary environment variables:

1. Enable Credits in Configuration
   • Open src/config/website.tsx and locate the credits section.
   • Set enableCredits: true to enable the credits system.
   • Set enablePackagesForFreePlan, only paid users can purchase extra credit packages by default, if set to true, free users can also purchase credit packages.
   • Set registerGiftCredits to configure whether to give credits on registration, the number of credits to gift, and the expiration time.

export const websiteConfig = {
  // ...other config
  credits: {
    enableCredits: true, // Enable credits system
    enablePackagesForFreePlan: false, // disable free users to purchase credits
    registerGiftCredits: {
      enable: true, // Give credits on registration
      amount: 10, // Number of credits to gift
      expireDays: 30, // Optional: days before credits expire
    },
    packages: {
      basic: {
        id: 'basic',
        amount: 100,
        price: {
          priceId: process.env.NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC!,
          amount: 990,
          currency: 'USD',
        },
        popular: false,
      },
      // ...other packages
    },
  },
  // ...other config
}

2. Configure Credits in the Price Plan
   • Open the file src/config/website.tsx and locate the price.plans section.
   • Set credits field to true to enable credits in this price plan.
   • Set amount field to 100 to set the number of credits in this price plan.

export const websiteConfig = {
  // ...other config
  price: {
    plans: {
      free: {
        id: 'free',
        // ...other config
        isFree: true,
        isLifetime: false,
        credits: {
          enable: true,
          amount: 50,
          expireDays: 30,
        },
      },
      // ...other plans
    },
  },
  // ...other config
}

3. Configure Credit Packages
   • Define credit packages under credits.packages, there are 4 credit packages by default.
   • Each package includes an id, credits amount, price (Stripe priceId, see below Set Stripe Price IDs), and optional fields like popular, expireDays.
   • Currency is USD, currently only USD is supported.

packages: {
  basic: {
    id: 'basic',
    amount: 100,
    price: {
      priceId: process.env.NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC!,
      amount: 990,
      currency: 'USD',
    },
    popular: false,
    expireDays: 30,
  },
  // ...
}

4. Set Stripe Price IDs
   • Stripe price IDs are used to link credit packages to Stripe products and prices.
   • Go to Stripe Dashboard, create a new product, and set prices for each credit package.
   • Add Stripe price IDs for each credit package to .env file:

NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_STANDARD=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_PREMIUM=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_ENTERPRISE=price_...

5. Set Up Translations for Credit Packages
   • define the translated credit package names and descriptions in src/config/credits-config.tsx.
   • The corresponding translation files are in src/messages/en.json, src/messages/zh.json, etc.

export function getCreditPackages(): Record<string, CreditPackage> {
  const t = useTranslations('CreditPackages');
  const creditConfig = websiteConfig.credits;
  const packages: Record<string, CreditPackage> = {};

  // Add translated content to each package
  if (creditConfig.packages.basic) {
    packages.basic = {
      ...creditConfig.packages.basic,
      name: t('basic.name'),
      description: t('basic.description'),
    };
  }

  // Add other packages here...
  return packages;
}

6. Set Up Cron Jobs

Please refer to the Cron Jobs documentation to set up cron jobs for credit distribution and credit expiration.

Credits System Structure

The credits system is modular and consists of the following components:

Core Features

• Purchase Credits: Users can buy credit packages if credits are not enough.
• Gift Credits on Registration: Optionally grant credits to new users.
• Credit Expiration: Set expiration days for credits per package or for gifts.
• Track Credit Balance: Query current user credits securely.
• Credit Transactions: View detailed transaction history (purchases, usage, expiration, etc.).
• Custom Packages: Define any number of packages with different amounts, prices, and properties.
• Internationalization: Support for translated package names and descriptions.
• Secure Server Actions: All credit operations are protected and validated.
• Zustand Store: Manage credits state globally in the app, and use it in React components via hooks.

Best Practices

1. Enable Only When Needed: Set enableCredits: true only if your business model requires credits.
2. Validate All Actions: Use provided server actions for all credit operations to ensure security and validation.
3. Handle Expiration: Set expireDays for packages or gifts if you want credits to expire.

Test

You can access the http://localhost:3000/test page to test the credits system, there is a button to consume 100 credits, and the credit balance will be displayed after consumption.

Video Tutorial

Next Steps

Now that you understand how to work with credits in MkSaaS, explore these related integrations: