Subscriptions

Overview

Subscriptions let administrators create recurring billing inputs that automatically generate Usage Records on a schedule.

They are intended for billable items that recur on a fixed cadence without requiring a live usage session or manual entry each time.

Subscription
     ↓
Subscription Cycle
     ↓
Usage Record
     ↓
Charge
     ↓
Invoice
     ↓
Statement

Navigate to Billing → Subscriptions to create and manage them.

Current Scope

Recurring subscriptions currently support Materials as the billable item type.

When to Use Subscriptions

Subscriptions are useful when a user should incur a recurring billable usage record on a fixed interval.

Common examples:

• Monthly material-based service fees
• Annual recurring consumable allocations
• Fixed recurring billable quantities that should flow into normal billing
• Any scenario where a usage record should be generated on a schedule (memberships, locker rentals, etc.)

Core Concepts

Subscription

A Subscription defines:

• The billable item
• The user the usage belongs to
• The project that will receive the resulting charges
• The recurring interval
• The quantity and unit to generate
• When recurring generation starts and ends

Subscription Cycle

A Subscription Cycle is the record of a single scheduled billing period for a subscription.

Each cycle tracks:

• The period start and end
• When the cycle was scheduled
• Whether usage generation succeeded or failed
• The resulting usage record, when one was created

Generated Usage Record

Each successful cycle creates a Usage Record whose source is the corresponding Subscription Cycle.

That usage record then follows the normal billing pipeline:

• Rate resolution
• Charge generation
• Invoice generation
• Statement generation

Creating a Subscription

Required Fields

• Billable: The recurring item to bill
• User: The user associated with the generated usage
• Project: The project that accumulates the resulting charges
• State: Usually Active
• Interval Unit: Month or Year
• Interval Count: The recurrence frequency, such as every 1 month or every 3 months
• Quantity: The raw quantity to generate each cycle
• Starts At: The date and time recurring generation begins

Optional Fields

• Unit: A permitted billing unit for the selected item and project
• Ends At: Stops future generation after the subscription reaches this boundary
• Metadata: Optional key-value information for internal tracking (ex: locker number, service tier, etc.)

Validation Rules

Subscriptions are validated against the same billing model used elsewhere in Colabmacs.

The system requires:

• The selected billable item still exists
• The selected user and project still exist
• The selected user belongs to the selected project
• The project is active
• The billable item can be billed
• A matching rate exists for the project when the cycle is processed

Unit Selection

If no unit is selected, the generated usage will fall back to the unit defined by the resolved rate.

States

Subscriptions support the following lifecycle states:

State	Meaning
Active	Eligible for scheduled processing when due
Paused	Retained, but not processed while paused
Cancelled	No future scheduled processing
Expired	Automatically reached when the subscription passes its configured end boundary

Only active subscriptions with a due Next Run At value are picked up by the scheduled processor.

How Processing Works

Scheduled Processing

Colabmacs runs a scheduled job that looks for active subscriptions whose Next Run At has arrived.

For each due period, the system:

1. Creates or reuses the matching Subscription Cycle
2. Resolves the appropriate Rate for the subscription's billable item and project
3. Creates a Usage Record sourced from that cycle
4. Allows the normal charge pipeline to generate a Charge
5. Advances Last Run At and Next Run At

Idempotency

Subscription processing is designed to be idempotent for a billing period:

• Reprocessing the same cycle does not create duplicate usage records
• Reprocessing the same cycle does not create duplicate charges
• Existing successful cycles are recognized and reused

If Processing Fails

If a cycle cannot be processed, the cycle is marked as Failed and the error is stored on the cycle record.

Common causes include:

• Missing rates
• Deleted billable items
• Inactive projects
• Users no longer assigned to the selected project

If multiple periods are overdue, processing stops at the first failure. Later periods wait until the problem is resolved and processing is retried.

Reviewing Results

Subscription Detail

Each subscription includes:

• A Cycles tab showing the generated subscription cycles
• A Usage Records tab showing the usage records created from those cycles

Usage Record Detail

Generated usage records appear in the standard Usage Records area and identify their Source as a subscription cycle.

This makes recurring billing auditable in the same place as session-based or manually created usage.

Charges, Invoices, and Statements

Once the usage record exists, downstream billing behaves exactly like any other usage-driven charge:

• Charges are created from the generated usage
• Invoices collect the resulting charges
• Statements consolidate invoices at the team level

Operational Notes

• Subscriptions are available from the Billing section in Nova
• Access depends on subscription-related permissions
• The scheduled processor only considers subscriptions that are both active and due
• If an end date is configured, the subscription eventually transitions to Expired

Related Topics

• Billing Guide
• Usage Records
• Billing Rules