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)

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

1. Users 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

Charges

Charges represent billable amounts derived directly from Usage Records.

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.

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.

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)

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 to Teams and Projects and referenced by billing rules.

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.

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 job that generates monthly billing Statements for all Teams.

This standalone action is available from Statements page and allows you to manually trigger the scheduled job that runs monthly to generate Invoices and Statements.

Scheduled Generation

Monthly Job: Generate Monthly Billing Statements

This automated job runs monthly to generate Invoices and Statements for all Projects that have charges within the period.

This scheduled job:

• Generates Invoices and Statements
• Includes all Projects with billable Charges
• Is idempotent
• Can be triggered manually

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 monthly 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
• Projects

What's Next?

See the Billing Rules for advanced Charge customization.