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

# Subscriptions explained

> Understand what subscriptions are, how they drive billing, and what happens when they change

<Info>
  This page explains how subscriptions work as a concept. For step-by-step instructions on creating and managing subscriptions in the app, see [Subscriptions](/billing-workspace/subscriptions-workspace) in the Billing Workspace section.
</Info>

## What is a subscription?

A subscription is the link between a customer and a plan. It is the central object in Saasybill. Every invoice, credit note, and billing event flows from a subscription.

When you create a subscription, you define:

* **Who** is being billed (the customer)
* **What** they are being billed for (the plan)
* **How many** units apply
* **When** billing starts

From that point on, Saasybill manages the billing cycle automatically.

***

## How subscriptions drive invoices

At each renewal, Saasybill calculates the amount due based on the subscription's current units and plan pricing, then creates an invoice directly in Xero.

The revenue type on each invoice is classified automatically:

| Invoice type  | When it applies                                             |
| ------------- | ----------------------------------------------------------- |
| **New**       | The first invoice on this subscription                      |
| **Renewal**   | Every subsequent renewal invoice                            |
| **Expansion** | When a customer increases units on an existing subscription |

This classification determines which Xero account code the invoice line item posts to.

***

## Subscription lifecycle

A subscription moves through a defined set of states from creation through to completion or cancellation.

```mermaid placement="bottom-right" actions={false} theme={null}
flowchart LR
    START([Create]):::start

    START -->|future start date| A([Pending]):::pending
    START -->|past start date| B([Active]):::active

    A --> B
    B --> C([Scheduled to end]):::scheduled
    B --> D([Ended]):::ended
    C --> E([Complete]):::complete

    classDef start fill:#f9fafb,stroke:#d1d5db,color:#6b7280
    classDef pending fill:#dbeafe,stroke:#93c5fd,color:#1d4ed8
    classDef active fill:#dcfce7,stroke:#86efac,color:#15803d
    classDef scheduled fill:#f3f4f6,stroke:#d1d5db,color:#374151
    classDef complete fill:#f3f4f6,stroke:#d1d5db,color:#374151
    classDef ended fill:#fee2e2,stroke:#fca5a5,color:#b91c1c
```

| Status       | What it means                                                                          |
| ------------ | -------------------------------------------------------------------------------------- |
| **Pending**  | Created with a future start date. Not yet live but the first invoice has been created. |
| **Active**   | Live and billing. Renews automatically at each period.                                 |
| **Complete** | Reached its schedule end date.                                                         |
| **Ended**    | Stopped immediately or cancelled manually.                                             |

<Info>
  An **Ended** subscription can be reverted back to **Active** if done so before it's scheduled renewal date.
</Info>

***

## Units

Units represent the quantity being billed: licences, users, seats, or whatever measure the plan defines. The plan sets the minimum unit floor; individual subscriptions can override this floor if needed.

There are two unit values tracked on a subscription:

* **Current units:** the live count, updated whenever a change is made
* **Paid units:** the count that the most recent invoice was raised against

These two values may differ mid-cycle if a unit change has been made but not yet invoiced, for example, when a non-prorated update is made.

***

## What happens when a subscription changes

Mid-cycle changes to a subscription, such as increasing or decreasing units, trigger a billing adjustment. Whether this results in an invoice or a credit note depends on the direction of the change and your proration settings.

| Change         | Outcome                                                                                                                                                                                                                                 |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Units increase | A prorated invoice is generated for the additional amount - unless the increase results in a lower payable amount, such as when upgrading tiers on a volume plan, in which case a prorated credit note for the difference is generated. |
| Units decrease | No immediate billing document. The change takes effect at the next renewal.                                                                                                                                                             |
| No proration   | The change takes effect at the next renewal.                                                                                                                                                                                            |

The **effective date** of the change determines how the prorated amount is calculated. See [Billing changes](/core/billing-changes) for the full logic.

***

## Subscription level overrides

Individual subscriptions can override certain defaults set at the company or plan level:

* **Discount:** a percentage reduction that always applies to the base plan amount. When adding optional items, you can also choose to apply it to individual add-ons or charges.
* **Minimum invoice amount:** the threshold below which an invoice is not approved
* **Invoice due date:** the number of days after the invoice date that payment is due
* **Minimum units:** overrides the plan level minimum for this specific subscription

***

## Optional items

### Add-ons

Add-ons are optional recurring extras that can be attached to a subscription. They are billed alongside the base plan amount at each renewal.

See [Add-ons](/product-catalogue/addons) for the full details.

### Charges

Charges are one-time fees that can be added to a subscription. Unlike add-ons, charges are billed once and do not recur at renewal.

See [Charges](/product-catalogue/charges) for the full details.