Subscriptions

This page covers how to use the Subscriptions section of the app. For a conceptual explanation of how subscriptions work, what drives invoices, and how lifecycle states behave, see Subscriptions explained in Core Concepts.

The Subscriptions page is your operational view of all billing activity. From here you can see every subscription across your customer base, create new ones, update units, and track what’s happened on each subscription over time.

The subscriptions list

Click Subscriptions in the sidebar to see all subscriptions in your organisation.

Tabs

Filter the list by status using the tabs at the top:

Tab	What it shows
All	Every subscription regardless of status
Pending	Subscriptions created but not yet started
Active	Currently live and billing subscriptions
Complete	Subscriptions that have reached their scheduled end
Ended	Subscriptions that were ended manually or cancelled

Filtering and searching

Search: free text search across subscription fields
Sort: order by date or other fields
Filter: filter by Start Date, Renewal Date, or End Date
Download: export all subscriptions in your organisation as a CSV file

What each row shows

Each subscription row displays:

Column	Description
Customer · Plan	The customer and plan name. Click to open details.
Dates	Relevant dates and days until based on the current status.
Units	Current unit count and unit type.
Subscription Value	The subscription amount per billing period.
Status	Pending, Active, Complete, or Ended
Subscription History	Click to view the unit change history for that subscription.

Attention needed

When one or more subscriptions require action, such as an invoice discrepancy or a credit note that needs allocating, an Attention Needed banner appears at the top of the page. Click View to go to the affected subscription.

Attention needed prompts on details page

Two types of alerts can appear at the top of the subscription details page:

Invoice attention: shown when the most recent invoice has a discrepancy.
Credit note attention: shown when a credit note requires action.

Recommended actions are shown to fix the error depending on the event.

Creating a subscription

Click New in the top right to open the new subscription form. You can also create a subscription directly from a customer’s details page by clicking Add.

Required fields

Customer: search for and select the customer. If expected customers aren’t appearing, a prompt will suggest how to find them. Plan: select the plan that defines the pricing and billing structure. The plan’s subscription period determines when the first renewal will occur. Number of Units: enter the total unit count. This must be above the plan’s minimum units. Subscription Start Date: the date billing begins. The estimated renewal date is shown automatically below the picker.

If the estimated renewal date is within the Invoice Create Days set in your Company Settings, Saasybill will confirm that the subscription will renew immediately on save (unless you are in Setup Mode).

Optional fields

Subscription End: set the subscription to automatically end after a specified number of billing cycles. The estimated end date is shown once you enter a cycle count.

Advanced settings

Click View Advanced Settings to access:

Setting	What it does
Discount percentage	Applies a percentage reduction to the plan amount. The discount always applies to the plan. When selecting add-ons and charges below, you can also choose to apply it to individual optional items.
Optional items	Add recurring add-ons or one-time charges to this subscription. For each item, choose whether the subscription discount percentage applies , or doesn’t apply (default).
Minimum units	Overrides the plan level minimum for this specific subscription. Must be greater than the plan’s minimum units.
Minimum invoice amount	Overrides the company level minimum invoice threshold before an invoice is set to Awaiting Approval.
Invoice due date	Overrides the default number of days after the invoice date that payment is due.

Click Save to create the subscription. If you are not in Setup Mode, the appropriate invoice will be created in Xero immediately.

Subscription details

Click any subscription’s Name to open its details page. The details page is split into up to six sections depending on the configuration.

Subscription Details

Shows the general details and settings of the subscription.

Subscription

Field	Description
Company	The customer this subscription belongs to
Plan	The plan this subscription is on
Start Date	When the subscription started
Renewal Date	The next scheduled renewal date
End Date	When the subscription is scheduled to end (if set)
Subscription Period	The billing frequency
Status	Current status

Pricing

Field	Description
Current Units	Live unit count. Click to update units.
Paid Units	Total number of units paid for.
Amount	Subscription amount per period (after any discount).
Credit Balance	Total available credit on this subscription. Used against future invoices.
Discount	Discount percentage applied (if any).

Invoicing settings

Field	Description
Minimum Units	The minimum number of units the subscription must have.
Minimum Invoice Amount	The minimum threshold before an invoice is set to Awaiting Approval.
Invoice Due Date	The number of days after the invoice date that payment is due.

Add-ons

The Add-ons section lists all add-ons currently attached to the subscription. Each row shows the add-on’s name, add-on ID, description, and price per billing period.

You cannot remove add-ons once they have been added to a subscription.

To attach a new add-on, click Add an add-on, then select an existing add-on from you Product Catalogue. Once selected, a new invoice will be generated billing for the new add-on.

Add-ons can only be added to Pending subscriptions.

Invoices

The Invoices section shows all invoices that have been generated on this subscription. Each invoice row displays:

Column	Description
Date	The date the invoice was generated
Number	The Xero invoice reference number
Amount (ex. tax)	The invoice total excluding tax
Amount (inc. tax)	The invoice total including tax
Xero Status	The current status in Xero
Sent	Whether the invoice has been sent to the customer

Click the on any invoice to expand it and see the line items and actions available for that invoice.

For more information on invoices, see the Invoices documentation.

Click Download data to export all line items on the subscription as a CSV file.

Invoices are synced to and managed in Xero. To update an invoice’s status, change it in Xero.

Deferred Line Items

The Deferred Line Items section shows line items that have been generated but not yet invoiced. They will be included in the next renewal invoice when the subscription renews. Each line item row shows:

Column	Description
Effective Date	The date the charge took effect
Item	The item being charged
Amount	The charge amount of the line item
Invoice now	Create an invoice and bill for this line item immediately
	Click to show more details of the line item

If you need to invoice a line item before the scheduled renewal date, click Invoice now. This immediately creates an invoice in Xero for that line item and it will no longer be billed on renewal.

Credit Notes

The Credit Notes section shows all credit notes that have been generated on this subscription. Each credit note row displays:

Column	Description
Date	The date the credit note was generated
Number	The Xero credit note reference number
Amount (ex. tax)	The credit note total excluding tax
Amount (inc. tax)	The credit note total including tax
Xero Status	The current status in Xero
Application	Unapplied, Partial, Applied, or Error

Click the on any credit note to expand it and see the line items and actions available for that credit note.

Credit notes are generated automatically by Saasybill when an increase in units results in a lesser payable amount. They are synced to and managed in Xero. For more information, see Billing Changes.

Click Download data to export all credit note line items on the subscription as a CSV file.

Subscription History

The history table shows every unit change over the subscription’s lifetime:

Column	Description
Created Date	The date the change was made in Saasybill
Effective Date	The date the change took effect
Previous Units	The unit count before the change
Updated Units	The unit count after the change
Unit Change	The delta: the positive or negative unit movement
Type	The type of change (New, Renewal, Expansion, or Contraction)
Charge Type	The type of associated charge created on an update: N/A: The change was made within the paid units or amount Charged: The change was prorated and charged immediately Deferred: The change was prorated and charged on renewal No Charge: The change was not prorated and not charged Credit: The change was prorated and generated a credit note

Click Download Data to export the history as a CSV file. You can also click the of any subscription in the subscriptions list to view a simplified unit change history at a glance.

Updating units

To update the number of units on an active subscription, click the current units in the Pricing section on the subscription details page. You can also update units directly from the subscriptions list row by clicking the units. An icon will show if the units can be updated.

Subscriptions Page Update Units Screenshot

Enter the new total unit count, not the change amount. Proration toggle: turn on to apply a prorated charge for a mid-cycle change. When enabled, choose a proration behaviour:

Immediate: takes effect from the chosen effective date; a prorated invoice is created in Xero immediately
**On Renewal: **takes effect from the chosen effective date; a prorated line item is added to the Deferred Line Items table to be billed on the renewal invoice

Credit notes are always generated as a prorated update and are creditted immediately. You can not adjust the proration behaviour in this case.

Effective date: the date from which the new unit count applies. Can be backdated or forward-dated within the current period. Saasybill will show additional informational prompts based on your inputs and a description that summarises the change. If the renewal is within one month, you’ll also be asked whether to add the updated amount to the upcoming renewal invoice rather than raising a separate one. Click Confirm to apply. The subscription updates immediately and Xero receives the relevant document.

For a full explanation of how proration is calculated and when invoices vs credit notes are created, see Billing changes.

Ending a subscription

From the subscription details page you have three options:

Action	What it does
End subscription at period end	Schedules the subscription to stop at the next renewal date. Billing continues normally until then.
End subscription now	The subscription is stopped immediately. You cannot make any more updates to the subscription and no refund for the unused period is given.
Delete subscription	Permanently removes the subscription immediately. Invoices are voided and deleted in Xero.

To end a subscription: open the details page, click End Subscription, and choose whether you want the subscription to end immediately or at the current period end.

A deleted subscription cannot be recovered. Use End subscription to keep the subscription

Reverting a subscription: if a subscription has been ended immediately but has not passed its renewal date yet, you can revert it back to active from the details page by clicking Revert subscription.

Editing other fields

To edit other fields on a subscription click Edit details on the details page to update:

Subscription Start Date (on Pending subscription only)
Subscription End

Click View Advanced Settings to update:

Discount Percentage (on Pending subscriptions only)
Minimum Units
Minimum Invoice Amount
Invoice Due Date

Getting started

Core concepts

Billing workspace

Product catalogue

Settings

The subscriptions list