Usage, Billing, and Invoicing
Usage, Billing, and Invoicing
Overview
CMS collects or imports platform usage, generates billing rows, displays billing grids and charts, creates invoices, and calculates commissions.
Usage Collection
Usage collection depends on platform:
| Platform | Collection model |
|---|---|
| Azure Stack | Collect usage and price through CMS meter/SKU pricing. |
| Azure Local | Discover VM and disk allocation, generate UsageData, then price through CMS. |
| Public Azure | Import Azure cost records, map by resource group tag, and generate CMS billing rows. |
| CloudStack | Collect CloudStack usage and price through offer/template pricing. |
Scheduled usage collection runs through scheduled jobs. Manual region update actions dispatch through the same platform-aware usage service path.
Billing Generation
Billing persists daily Billing rows generated from daily usage rows or imported Azure cost records. Daily windows use half-open date ranges, where the start is included and the end is the next day.
Monthly compatibility routes remain available:
| Route | Purpose |
|---|---|
GET /api/v1/billing/generate/{yyyy-MM} |
Generate daily rows for a calendar month. |
GET /api/v1/billing/yearmonth/{yyyy-MM} |
Read rows visible in the selected month. |
POST /api/v1/billing/generate/range?start=yyyy-MM-dd&end=yyyy-MM-dd |
Platform-admin date-range generation. |
GET /api/v1/billing/range?start=yyyy-MM-dd&end=yyyy-MM-dd |
Authenticated date-range read. |
The application and scheduled usage flows call GenerateMonthlyBillingRecords(period_start, period_end) as the compatibility entry point. After the daily billing migration is applied, that procedure wraps daily billing generation.
Billing Page
The Billing grid supports:
- Date range selection for daily rows.
- Year/month selection for monthly aggregation mode.
- Region, tenant, and subscription filters.
- CSV export of filtered rows.
- Billing details with pricing, hosting, and resource information.
- Summary cards for the selected range and comparable previous range.
The Billing category setting DefaultBillingAggregationMonthly controls whether the grid opens in monthly aggregation mode. Users can still toggle modes in the current page session.
Billing Selection Mode
The Billing > General setting UseOverlapUsageSelection controls how generated billing selects usage rows.
| Setting value | Behaviour |
|---|---|
false |
Use rows whose usage start time falls inside the billing day or month. |
true |
Use period overlap so boundary-spanning rows are included once in the applicable billing period. |
Enabling overlap mode can increase generated totals because rows overlapping the beginning of a period may now be included.
Invoices
Invoices consume daily billing rows while preserving monthly and quarterly cadences.
| Invoice type | Behaviour |
|---|---|
| MonthlyInvoice | Actual consumption for the selected coverage month. |
| QuarterlyInvoice | Future three-month invoice based on the previous three completed months, with projection, optional override, and true-up metadata. |
Invoice generation is limited to platform administrator and platform service roles.
Invoice visibility settings control whether invoice tabs and widgets are visible to tenants, partners, and distributors. The API enforces the same visibility settings server-side. Platform roles can view invoices regardless of these visibility settings.
Billing Status
The Billing Status tab groups status by tenant and subscription. It shows overdue, issued, uninvoiced, and paid totals for last month, last quarter, the selected/current month, and current quarter-to-date.
Preview and generated invoices are treated as uninvoiced for status reporting.
Commissions
Commission summaries and charts are scoped by role. Routes that accept a related partner or distributor ID validate that non-platform callers can access the requested entity before returning chart data.
Operational Notes
Take a MySQL backup before applying daily billing, billing selection, invoice visibility, quarterly invoicing, tenant invoice type, scheduled notification, Azure Stack SKU normalization, or Azure Stack managed disk meter repair scripts.
Backfill daily billing only after testing in a non-production copy and reviewing reconciliation output.
Known Gaps
Manual Review Required: Historical Public Azure backfill helper work is listed as backlog. Public Azure historical regeneration should currently be handled through the Azure billing ingestion path for the required region and date ranges.