Billing Guide

Executive Summary (For Finance & Admins)

Colabmacs billing converts usage (time, materials, and services) into Charges, groups those Charges into Invoices, and then consolidates Invoices into Statements at the Team level.

Pricing is controlled through Rate Groups, which act as pricing models. Each Project selects one rate group, and only rates from that group are eligible for billing.

If no matching rate exists, nothing is billed — by design. This prevents accidental Charges and ensures a clean, auditable billing pipeline.

How Billing Works (High-Level Flow)

Subscriptions (scheduled usage)
     ↓
Usage Records
     ↓
Rate Matching (via Rate Groups)
     ↓
Charges
     ↓
Invoices (Project-Level)
     ↓
Statements (Team-Level)
     ↓
Exports (Downloadable Artifacts)

1. Users or automated subscriptions generate Usage Records
2. The system attempts to match a rate
3. Charges are created (or skipped)
4. Charges are grouped into Invoices
5. Invoices are consolidated into Statements
6. Statements can be exported and distributed

Each layer exists independently and supports its own billing rules.

Core Concepts

Rate Groups (Pricing Models)

A Rate Group defines which pricing model applies to a Project.

Examples:

• Academic
• Industrial
• Internal
• Discounted

Rate groups organize rates but do not define prices themselves.

Rates (Prices)

A Rate defines the actual price for a billable item within a specific rate group.

Rules:

• A billable item may have rates in multiple rate groups
• A billable item may not have more than one rate in the same rate group

After Hours Rates

Rates can define different pricing outside business hours.

How it works:

• Business hours are evaluated per resource
• Time is split into in-hours and after-hours segments
• A weighted effective rate is calculated

Blended Rate Formula

$$\text{R}_\text{ effective} = \left( \frac{\text{T}_\text{ day}}{\text{T}_\text{ total}} \times \text{R}_\text{ day} \right) + \left( \frac{\text{T}_\text{ after\_hr}}{\text{T}_\text{ total}} \times \text{R}_\text{ after\_hr} \right)$$

Variable	Description
Reffective	Effective Rate
Rday	Rate During Business Hours
Rafter_hr	After Hours Rate
Tday	Time During Business Hours
Tafter_hr	Time After Business Hours
Ttotal	Total Time

Project Types & Projects

• Project Types define default rate groups
• Projects inherit the default rate group
• Projects may override the rate group if permitted

Subscriptions (Recurring Usage Sources)

Subscriptions create scheduled Usage Records on a recurring interval.

They are useful when billing should occur on a fixed cadence without a live session or manual usage entry each time.

Key points:

• Subscriptions generate usage first, then follow the normal charge pipeline
• Each scheduled period creates a Subscription Cycle
• Successful cycles create a Usage Record
• Charges, Invoices, and Statements are then produced through the existing billing flow
• Current support is focused on recurring Material billing

For operational details, see Subscriptions.

Charges

Charges represent billable amounts derived directly from Usage Records.

Those Usage Records may come from:

• Completed usage sessions
• Manual administrative entry
• Recurring subscription cycles

Charge Generation Rules

A Charge is created only when all conditions are met:

• A Usage Record exists
• The billable item has a rate
• The rate belongs to the Project’s rate group

Charge States

State	Description
PENDING	Editable, not yet Invoiced
BILLED	Locked and attached to an Invoice
PAID	Read Only

Charge Regeneration

Archived Rates & Charge Regeneration

When a Charge is created, a snapshot of the Rate is retained to ensure historical accuracy. When a Charge is regenerated, it will use the archived Rate unit & value to maintain consistency.

If the underlying Rate has changed since the original Charge was created, the regenerated Charge will use the ARCHIVED Rate. If you want to apply the new Rate, you must first delete the existing Charge before regenerating, this will create a new Charge with the current Rate. This approach ensures that historical Charges remain accurate and consistent, while still allowing for updates when necessary.

Regeneration Behaviour

Charge regeneration behaves differently depending on whether the original Charge is still editable.

If the Charge is still Pending or Billed

If the existing Charge is still Pending or Billed, regeneration updates the original Charge in place.

This means the system will:

• Recalculate the billable quantity and total
• Continue using the archived Rate from the original Charge
• Update the existing Charge record rather than creating a second Charge

If the Charge is already Paid

If the existing Charge is already Paid, the original Charge remains read-only.

In that case, Colabmacs computes what the Charge would be now and compares it to the original billed Charge. If there is a difference, the system creates an Offset Charge linked to the original Charge.

The Offset Charge:

• Preserves the original billed or paid Charge unchanged
• Stores only the delta between the original Charge and the newly computed result
• Uses the same usage_record_id so the adjustment remains attached to the same usage
• Links back to the original Charge through related_charge_id
• Receives a new created_at timestamp so it can appear in future invoice runs
• May be positive or negative

This allows Colabmacs to preserve the integrity of already-issued billing artifacts while still recording corrections.

Positive and Negative Offsets

• If the recalculated amount is higher than the original billed amount, the Offset Charge is a positive adjustment
• If the recalculated amount is lower, the Offset Charge becomes a negative adjustment or credit
• If there is no effective difference, no Offset Charge is created

If an Offset Charge already exists for the same base Charge, Colabmacs updates that existing offset rather than creating duplicates. If the net difference returns to zero, the offset is removed.

Operational Implication

When reviewing regenerated billing on locked Charges, think of the ledger as:

Base Charge (original billed amount)
        +
Offset Charge(s) (later adjustments)
        =
Effective billed total

This is why the original Charge detail can remain historically accurate while newer invoice periods still capture corrections.

Some key considerations:

• During regeneration, the system will attempt to locate the original Rate. If it exists, it will use the archived unit and value, and will apply any billing rules from the original Rate.
• If the original Rate has been deleted, the Charge will fall back to the Rate associated with the Usage Record, and will apply the original unit and value. It will then apply any billing rules based on that Rate.
• Offset Charges are internal billing adjustments generated during regeneration of read-only Charges.

Adjustments

Charges, Invoices, and Statements store two totals:

• Raw Total
• Total

The Adjustment value represents the difference between them.

Adjustments are:

• Generated automatically
• Not manually editable
• Positive or negative

Invoices

Invoices collect pending Charges into billable documents.

Invoices support:

• Cap rules
• Scale rules
• Tag-based rule application
• Export generation
• Mark as Paid (locks Invoice and Charges)

Billing Instructions

Project Types can include optional Billing Instructions that are added to any Invoice generated from a project of that type. This is a useful place to include project-specific billing notes or instructions for finance teams.

Statements

A Statement is the top-level billing object.

Statements:

• Are generated per Team
• Represent a monthly billing period
• Contain Invoices
• Support billing rules
• Support export generation
• Can be marked as paid (locks Statement, Invoices, and Charges)

Billing Rules & Scope

Rules apply only at the level they are defined:

• Charge rules → Charges
• Invoice rules → Invoices
• Statement rules → Statements

Tags & Rule Targeting

Tags can be applied at multiple levels in Colabmacs and can influence billing in different ways:

• Team and Project tags can be used by Invoice and Statement rules
• Usage Record tags can be used by Charge Rules

This allows administrators to target billing behavior more precisely without changing the underlying Project, Rate Group, or billable configuration.

Usage Record Tags + Charge Rules

When a Usage Record has one or more Tags, any Charge Rules attached to those Tags are evaluated when the Charge is generated.

This is especially useful for operational or accounting classifications such as:

• in-kind
• failed-run
• internal-review

Example: in-kind

One common pattern is:

1. Create a Tag called in-kind
2. Attach a Charge Rule to that Tag that caps the billed quantity to 0
3. Apply the in-kind tag to selected Usage Records

This allows the Usage Record to remain associated with the correct Project and retain its full history, while producing a zero-value Charge for the tagged usage.

Billing Operations & Generation Workflow

Operational Actions

This section documents the operational actions that are available in the Admin section for each model. Actions are available for manual execution and are also used by scheduled jobs. They are gated by permissions and may not be visible to all users.

All billing artifacts are idempotent, meaning:

• Regenerating will update existing artifacts
• Overlapping periods do not duplicate Charges
• Only unattached Charges are added
• Existing exports are reused unless deleted

This ensures billing remains consistent and auditable.

Usage Records

Action: Create Charges

Generates or regenerates Charges for selected Usage Records.

Charges are:

• Generated automatically when usage is created
• Automatically regenerated if s Usage Session/Records are modified
• Available for manual regeneration

Manual regeneration is useful when:

• Billing rules change
• Adjustments need recalculation

Rule changes do not automatically regenerate Charges to prevent unintended consequences. Manual regeneration allows for controlled updates when necessary.

Subscriptions

Subscriptions allow administrators to create recurring billing inputs that automatically generate usage on a schedule.

How Subscription Billing Works

1. An administrator creates an Active Subscription
2. A scheduled job looks for subscriptions whose Next Run At is due
3. The system creates or reuses a Subscription Cycle for that billing period
4. The cycle generates a Usage Record
5. Normal charge generation creates a Charge from that record
6. Invoice and Statement generation proceed as usual

Important Behaviours

• Only active subscriptions are processed
• Processing is idempotent for a cycle and does not duplicate usage or charges
• If a cycle fails, the error is stored on the cycle record
• If several periods are overdue, processing stops at the first failure
• When an end date is reached, the subscription can transition to Expired

Current Scope

Recurring subscriptions currently support Materials as billable items.

See Subscriptions for setup, states, and operational guidance.

Projects

Action: Generate Invoice

Generates or regenerates an Invoice for selected Projects.

Allows you to:

• Create a new Invoice
• Regenerate an existing Invoice
• Run on selected Projects

Only Charges not already attached to an Invoice are included.

Teams

Action: Generate Invoices

Generate or regenerates Invoices for all Projects under selected Teams.

Generate Invoices:

• Only (re)generates Invoices for Projects that belong to the selected Teams. Projects outside the selected Teams are not affected.
• Only consolidates existing Charges into Invoices. It does not create new Charges or modify existing Charges
• If the selected period overlaps with existing Invoices, only unattached Charges are added to the Invoice. No duplicate Charges are created.
• If an Invoice already exists for the selected period, it will be updated to include any new Charges that were generated since the last run. Existing Charges that are already attached to the Invoice will be re-evaluated for billing rules and adjustments, but will not be duplicated or removed unless the underlying Charge data has changed.

Action: Generate Statements

Generate or regenerates Statements for existing Invoices.

Generate Statements:

• Does not create new Invoices
• Only consolidates existing Invoices
• If the selected period overlaps with existing Statements, only unattached Invoices are added to the Statement. No duplicate Invoices are created.
• If a Statement already exists for the selected period, it will be updated to include any new Invoices that were generated since the last run. Existing Invoices that are already attached to the Statement will be re-evaluated for billing rules and adjustments, but will not be duplicated or removed unless the underlying Invoice data has changed.

Action: Generate Invoices & Statements

Generates or regenerates both Invoices and Statements for selected Teams.

Generate Invoices & Statements:

• Performs both the Generate Invoices and Generate Statements actions in a single step
• First generates Invoices for all Projects under the selected Teams, then consolidates those Invoices into Statements
• Ensures that all Charges are included in Invoices before Statements are generated
• If the selected period overlaps with existing Invoices or Statements, only unattached Charges and Invoices are added to the respective documents. No duplicates are created.
• If Invoices or Statements already exist for the selected period, they will be updated to include any new Charges or Invoices that were generated since the last run. Existing Charges and Invoices that are already attached to the respective documents will be re-evaluated for billing rules and adjustments, but will not be duplicated or removed unless the underlying Charge or Invoice data has changed.
• This is equivalent to the running the Generate Monthly Billing Statements job but scoped to selected Teams.

Invoices

Action: Generate Invoice Export(s)

Generates an export file for selected Invoices, assembles them into a batch (zip file), and delivers via email and in-app notification.

Invoice Export File:

• Contains a single Excel sheet with all the Invoice data, including a detailed breakdown of each Charge.

Exports Are:

• Cached and linked to the Invoice.
• Idempotent - if the process is run again, the existing export will be included in a new batch export
• Valid for 90 days
• Not regenerated unless deleted
• Delivered via email and in-app notification (based on preferences)
• Accessible from Exports panel and Invoice detail

Action: Mark as Paid

Marks selected Invoices (and associated Charges) as paid.

Effects:

• Makes Invoice read-only
• Marks associated Charges as paid and read only

Statements

Action: Generate Statement Export(s)

Generates an export file for selected Statements and associated Invoices, assembles them into a batch (zip file), and delivers via email and in-app notification.

• Option: Notify Team Owner

Statement Export File:

• Contains a multi-single Excel workbook which includes a Statement summary sheet, and the Invoice detail sheet for each Invoice in the Statement.

Generates:

• Statement export file for each Statement. This will also generate Invoice exports if they do not exist, or include the existing cached exports.
• A Statement summary document that is included in the export batch and contains a summary of all Statements in the batch, including total amounts and key details.

Exports Are:

• Cached and linked to the Statement.
• Idempotent - if the process is run again, the existing export will be included in a new batch export
• Valid for 90 days
• Not regenerated unless deleted
• Delivered via email and in-app notification (based on preferences)
• Accessible from Exports panel and Statement detail

Option: Notify Team Owner

When selected:

• Sends email notification to Team owners
• Ignores notification preferences
• Includes summary and download link

You may run this action without notifying to preview output.

Re-running with notification enabled:

• Creates a new export batch
• Reuses existing export files unless deleted

Action: Mark as Paid

Marks selected Statements (and associated Invoices and Charges) as paid.

Effects:

• Makes Statement read-only
• Locks Invoices and Charges beneath it

Action: Generate Monthly Billing Statements

Manually trigger the scheduled due billing job for all Teams.

This standalone action is available from the Statements page and allows you to manually trigger the same due-billing check used by the scheduler.

The actual billing period that is generated depends on the configured billing.auto_generate_frequency option.

Scheduled Generation

Daily Scheduler + Configurable Billing Periods

The billing scheduler runs daily at 09:00, and billing.auto_generate_frequency determines whether billing is generated monthly, quarterly, yearly, or not at all.

Automatic scheduled generation is controlled by two system options:

• billing.auto_generate_frequency
• timezone

billing.auto_generate_frequency

Valid values:

• monthly
• quarterly
• yearly
• manual

Behavior:

• monthly generates for the most recent fully completed calendar month
• quarterly generates for the most recent fully completed calendar quarter
• yearly generates for the most recent fully completed calendar year
• manual disables automatic billing generation

If billing.auto_generate_frequency is missing or invalid, Colabmacs falls back to monthly.

timezone

The timezone option controls how billing periods are interpreted.

It affects:

• Which dates count as the start and end of a billing month, quarter, or year
• Conversion of those local billing period boundaries into UTC when Invoices and Statements are generated

How the Daily Scheduler Works

The scheduler runs once per day and checks whether a billing period is due based on the configured billing options.

When scheduled billing runs, the system:

• Generates Invoices and Statements
• Includes all Projects with billable Charges in the due period
• Is idempotent
• Can be triggered manually from the Statements page

manual Mode

When billing.auto_generate_frequency = manual:

• No automatic Invoice generation occurs
• No automatic Statement generation occurs
• The daily scheduler runs, but skips billing generation
• Administrators can run billing manually using the existing billing tools or command flow if needed

Overlap Protection

If a due billing period would overlap existing Invoices or Statements, the run is skipped rather than regenerated.

This protects your billing records from accidental overlapping artifacts.

Option Matrix

billing.auto_generate_frequency	Result
monthly	Auto-run monthly for the most recent completed calendar month
quarterly	Auto-run quarterly for the most recent completed calendar quarter
yearly	Auto-run yearly for the most recent completed calendar year
manual	No automatic billing generation

Equivalent to: Generate Invoices & Statements (without Team filtering)

Exports

Excel exports are formatted to closely match standard billing documents.

When generating a Statement package:

• A summary file is included
• Invoice exports are included
• Packaged in a single zip archive

Exports remain valid for 90 days.

Deleting Exports

When you delete an export batch, it will remove the collection of export items as well. The underlying cached Excel file will only be deleted if it is no longer referenced by any other export item.

Notifications

Invoice export notifications:

• Respect user notification preferences

Statement export notifications:

• Always notify Team owners (optionally)
• Include Invoice summary
• Include Statement download link

Suggested Operational Workflow

1. Allow scheduled billing job to run
2. Review generated Invoices and Statements
3. Adjust billing rules if necessary
4. Regenerate Invoices or Statements if required
5. Filter Statements to desired billing period
6. Run Generate Statement Export(s)
7. Preview output without notifying
8. Re-run with “Notify Team Owner” enabled
9. Mark Statements as paid once finalized

This workflow ensures accurate, consistent monthly billing with minimal manual intervention.

Related Topics

• Billing Rules
• Usage Records
• Subscriptions
• Projects

What's Next?

See the Billing Rules for advanced Charge customization.