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:

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

src/config/website.tsx

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

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.

src/config/website.tsx

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

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:

.env

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

Credits

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.

src/config/credits-config.tsx

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

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

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

Credits System Structure

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

credits.ts

types.ts

client.ts

server.ts

This structure allows you to:

Define and manage credit packages
Track user credit balances and transactions
Integrate with Stripe for credit purchases
Use server actions for secure credit operations
Access credits state in React components via hooks and stores

Core Features

Purchase Credits: Users can buy credit packages via Stripe checkout.
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.
Popular Tag: Highlight popular packages in the UI.
Disable Packages: Hide or disable packages from being purchased.
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.
Extensible: Easily add new packages or change logic as needed.

Best Practices

Enable Only When Needed: Set enableCredits: true only if your business model requires credits.
Validate All Actions: Use provided server actions for all credit operations to ensure security and validation.
Customize Packages: Adjust credit amounts, prices, and expiration to fit your use case.
Track Transactions: Use the transaction log to audit and debug credit usage.
Handle Expiration: Set expireDays for packages or gifts if you want credits to expire.
Internationalize: Use translation hooks for package names and descriptions in the UI.
Test Thoroughly: Use Stripe test mode and test cards to verify the purchase flow.
Error Handling: Always handle errors and show user-friendly messages in the UI.