Billing & subscriptions

Agreements move through pending, billable, changed, payment-pending and closed states. Lines can only be edited while pending, protecting active agreements from unexpected changes to what is invoiced.

Each line references a price with either a fixed recurring amount or a usage-aggregation rule. All lines on a subscription share a currency and billing interval.

Raw usage events are matched and summed per billing period. Seven aggregation functions are supported: SUM, COUNT, COUNT_UNIQUE, FIRST, LAST, MAX and MIN. Aggregation rules are immutable and versioned, so historical invoices always reflect the rule that actually applied.

A cancellation records an effective date, a reason, and a final-invoice action. The final invoice can run to the end of the cycle, be prorated, or be issued immediately, so end-of-term billing behaves predictably.

Three layers resolve together: a platform ceiling, tenant capabilities, and per-customer capabilities. Every applicable layer must allow an operation, and numeric limits take the lower value.

Usage is counted per scope and compared before creation. Exceeding a limit returns a clear error naming the quota. Downgrades never delete existing resources - they only prevent new ones.

Administrators grant or restrict a capability with an optional end date and recorded reason. A trial is simply an override with an end date; expired overrides revert automatically.

Each billing event links to exactly one invoice line for a specific period - a clean trail from subscription activity to invoice.

Each subscription stores its UTC offset so cycle boundaries are computed in the customer's local time.

Multiple active subscriptions combine before overrides and the platform ceiling apply. Boolean capabilities OR together, and numeric limits sum.

When a subscription reaches the billable state, invoice generation is queued as a background job rather than run inline.