Billing plans

How to configure and use billing plans

Billing plans define your pricing model. A billing plan includes the schedule (or interval), features, pricing, limits and extra metadata.

The billing plan config is used to define the plans that are mapped to your billing provider and is also used to generate the pricing table UI.

Configure plans#

Plans are configured in packages/config/billing.config.ts.

import type { BillingPlan } from '@saas-ui-pro/billing'

export const plans: BillingPlan[] = []

Define a plan#

A plan is defined by a BillingPlan object.

export const plans: BillingPlan[] = [
  {
    id: 'basic@1',
    active: true,
    name: 'Basic',
    description: 'The basic plan',
    currency: 'EUR',
    interval: 'month',
    trialDays: 14,
    features: [],
  },
]

Let's break down the plan object:

• id: The id of the plan. This must be unique and is used to identify the plan in the code, it's recommended to use the {name}@{version} pattern, so you can create different versions of the same plan.
• active: Whether the plan is active. Setting this to false will disable the plan, and it won't be available to new users, but existing users will not be affected.
• name: The name of the plan. This is used to identify the plan in the UI.
• description: The description of the plan. This is used to describe the plan in the UI.
• currency: The currency of the plan. This is used to define the currency in the UI.
• interval: The interval of the plan. Can be day, week, month or year.
• trialDays: The trial days of the plan. Will start a trial period for new users.
• features: The features and entitlements of the plan.

Define a feature#

A feature is defined by a BillingFeature object. It can define features that are mapped to your billing providers pricing, and features that are for information purposes only.

export const plans: BillingPlan[] = [
  {
    id: 'basic@1',
    active: true,
    name: 'Basic',
    description: 'The basic plan',
    currency: 'EUR',
    interval: 'month',
    trialDays: 14,
    features: [
      {
        id: 'users',
        label: 'Users',
        priceId: 'price_1PLPKhHDkdkKDJkd',
        type: 'per_unit',
        price: 5,
        limit: 1,
      },
    ],
  },
]

This plan will include max 1 user and will be priced at €5 per month.

The feature object has the following properties:

• id: The id of the feature. This must be unique and is used to identify the feature in the code.
• label: The label of the feature. This is used to describe the feature in the UI.
• priceId: The price id of the feature. This is used to map the feature to the pricing in your billing provider.
• type: The type of the feature. Can be per_unit or metered.
• price: The price of the feature. This is the price of the feature per unit.
• limit: The limit of the feature. This is the maximum amount of the feature that is included in the plan.
• tiers: The tiers of the feature. This is used to define different pricing based on usage.

Define a tier#

Tiers allows you to define different pricing based on usage.

A tier is defined by a BillingPlanTier object. It can define tiers for your pricing model.

export const plans: BillingPlan[] = [
  {
    id: 'basic@1',
    active: true,
    name: 'Basic',
    description: 'The basic plan',
    currency: 'EUR',
    interval: 'month',
    trialDays: 14,
    features: [
      {
        id: 'users',
        priceId: 'price_1PLPKhHDkdkKDJkd',
        type: 'per_unit',
        limit: 10,
        tiers: [
          {
            upTo: 1,
            price: 0,
          },
          {
            upTo: 10,
            price: 5,
          },
        ],
      },
    ],
  },
]

This plan includes 1 free user and additional users are charged at €5 per month, with a maximum of 10 users.

The tier object has the following properties:

• upTo: The maximum amount of the feature that is included in the plan.
• price: The price of the feature. This is the price of the feature per unit.

Define a usage-based feature#

Usage-based features are features that are metered and charged per unit.

export const plans: BillingPlan[] = [
  {
    id: 'basic@1',
    active: true,
    name: 'Basic',
    description: 'The basic plan',
    currency: 'EUR',
    interval: 'month',
    trialDays: 14,
    features: [
      {
        id: 'minutes',
        label: 'Minutes',
        priceId: 'price_1PLPKhHDkdkKDJkd',
        type: 'metered',
        tiers: [
          {
            upTo: 1000,
            price: 0,
          },
          {
            upTo: 10000,
            price: 0.1,
          },
        ],
      },
    ],
  },
]

This feature will be free for the first 1000 minutes and then charged at €0.1 per minute.