> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voiceaiwrapper.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing Plans

> How to create plans, assign them to clients, and start a subscription.

## What a plan defines

A billing plan is the template that drives everything: how much a client pays, how often, how many minutes they get, whether they can buy extra minutes, and whether usage above the included limit is billed per minute.

When you start a subscription, the plan's terms at that moment are **snapshotted** onto the subscription. Editing a plan later does not change an already-running subscription.

### Plan attributes shown in the UI

<ResponseField name="Plan name" type="string" required>
  The display name shown to you and your client (for example, "Starter", "Growth", "100-Minute Pack").
</ResponseField>

<ResponseField name="Billing rhythm" type="Daily / Weekly / Monthly / Yearly">
  How often the billing period repeats. A count greater than one produces labels like "2× Monthly".
</ResponseField>

<ResponseField name="Currency" type="string" required>
  The currency for all amounts on this plan (ISO 4217 code, or a non-standard code such as USDT). This is snapshotted on the subscription and cannot be changed mid-subscription.
</ResponseField>

<ResponseField name="Recurring Billing" type="toggle">
  When enabled, the client is charged a flat fee each billing period. When disabled, no fixed fee applies (usage-only plans).

  **Badge states on plan and subscription cards:**

  * **Recurring · {amount} / {period}** - shown when enabled.
  * **Recurring · Off** - shown when disabled.

  <Expandable title="recurring amount fields">
    <ResponseField name="Recurring amount" type="decimal" required>
      The fixed amount charged each billing period. For example, `49.00`.
    </ResponseField>

    <ResponseField name="Included minutes per period" type="number">
      How many minutes the client gets each period at no extra charge. Shown in the badge as **"Minutes included: {count}"**. Unused minutes do **not** carry over to the next period.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="Usage-Based Billing" type="toggle">
  When enabled, minutes used beyond the included allowance (and any add-on wallet balance) are billed at a per-minute rate. When disabled, no per-minute charge applies.

  **Badge states on plan and subscription cards:**

  * **Usage · {rate}/min** - shown when enabled.
  * **Usage · Off** - shown when disabled.

  <Expandable title="usage rate fields">
    <ResponseField name="Per minute amount" type="decimal" required>
      The rate charged per minute of excess usage. For example, `0.10`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="Add-on packs · On / Off" type="badge">
  Whether this plan allows clients to purchase add-on minute packs. Must be **On** to assign or apply any add-on packs to a client on this plan.
</ResponseField>

<ResponseField name="Chat Enabled / 1 min = {count} chats" type="badge">
  When chat is enabled, included minutes and usage are measured in chat equivalent minutes. The displayed badge **"1 min = {count} chats"** shows the conversion rate.
</ResponseField>

<ResponseField name="Payment due after period start" type="days">
  How many days after the start of a billing cycle the payment request becomes overdue.
</ResponseField>

<ResponseField name="Grace after payment due" type="days">
  How many additional days after the due date the client has before the subscription is blocked.
</ResponseField>

<Tip>
  At least one of the recurring fee or usage rate must be set. A plan can also have both (a base fee plus per-minute overage beyond the included allowance).
</Tip>

***

## Assigning a plan to a client

Before a subscription can start, you must assign a plan to the client.

<Steps>
  <Step title="Go to the client's Billing tab">
    Open the client record and select the **Billing** tab. If the client uses External Billing, you see the **Current Plan** section.
  </Step>

  <Step title="Assign a Billing Plan">
    If no plan is assigned, the section shows **"Assign a Billing Plan"** with a dropdown: **Select a plan...**

    Each option in the dropdown is formatted as:

    ```
    Plan name - {recurring amount} · {per-minute rate} · {rhythm}
    ```

    Select the plan and click **Assign Plan**.
  </Step>

  <Step title="Confirm the assignment">
    After assigning, the card shows:

    * **"Currently assigned to client"** with a green checkmark.
    * The plan name, description, and badge summary (Recurring, Minutes included, Usage, Add-on packs, Chat).
    * The exact pricing block.
    * A **Start subscription** button.

    The client can now log in and see the assigned plan in their portal.
  </Step>
</Steps>

To remove the assignment, click **Remove Assignment** (the trash icon in the top-right of the assignment card). This removes the plan from the client but preserves any existing subscription history.

***

## Starting a subscription

You can start a subscription on behalf of the client, or the client can initiate it from their portal.

<Steps>
  <Step title="Click 'Start subscription'">
    On the assignment card, click the **Start subscription** button.
  </Step>

  <Step title="Confirm the dialog">
    A dialog appears: **"Start subscription for this client?"**

    It shows the plan name, price per period, and included minutes, then lists what starting will do:

    * **"Activate the subscription with a billing period beginning now."**
    * **"Initialize usage tracking (included minutes and add-on balance) for this plan."**
    * **"Create a payment request for this billing cycle when applicable."**

    Click **Start subscription** to confirm.
  </Step>

  <Step title="Subscription is live">
    The card switches to **"Current subscription"** and shows:

    * The current status badge (**Active**, **Past Due**, or **Blocked**).
    * The snapshotted **Plan terms** (the pricing and settings locked at start time).
    * **Billing period** - the start and end dates, plus a renewal badge.
    * **Payment due after period start** and **Grace after payment due** values.
    * Usage sections: included minutes progress, add-on wallet, and excess minutes if applicable.

    A first payment request is created automatically when there is a recurring fee.
  </Step>
</Steps>

***

## Plan terms snapshot

When a subscription starts, the exact plan terms (price, rhythm, included minutes, per-minute rate, add-on eligibility, chat conversion) are locked in as a **snapshot**. The card shows:

> *"Terms below reflect what was active when this subscription started."*

This means you can edit your plan catalog freely without disrupting running subscriptions. To apply new terms to a client, cancel the current subscription and start a new one.