Billing configuration
Each tenant has oneBillingConfig record that defines how and when they are invoiced. Only users with the super role can create or update billing configuration.
| Field | Type | Description |
|---|---|---|
flat_rate_amount | number | The fixed amount charged per billing period |
currency | string | Currency code for all charges (e.g., USD, KES) |
billing_frequency | monthly | annually | How often the tenant is billed |
billing_email | string | Email address that receives invoice notifications |
auto_generate_invoices | boolean | When true, invoices are created automatically at the start of each billing period |
billing_day_of_month | number | Day of the month (1–31) on which billing occurs |
payment_due_days | number | Number of days after the issue date before an invoice becomes overdue |
email_notifications | boolean | When true, the billing email receives notifications for new and overdue invoices |
billing_frequency accepts monthly or annually. The schema also supports quarterly as a valid value.Invoices
Every billing cycle generates anInvoice record. You can view the full invoice history for any tenant from the billing section of that tenant’s detail page.
| Field | Description |
|---|---|
invoice_number | Unique identifier for the invoice, used for reference and reconciliation |
amount | The invoiced amount in the configured currency |
status | Current payment status (see below) |
issue_date | Date the invoice was generated |
due_date | Date by which payment must be received |
paid_date | Date the invoice was marked as paid; null if not yet paid |
payment_reference | External payment reference or transaction ID; null if not recorded |
payment_method | Method used to pay the invoice; null if not recorded |
Invoice statuses
| Status | Meaning |
|---|---|
pending_payment | Invoice has been issued and is awaiting payment |
paid | Payment has been received and recorded |
failed | A payment attempt was made but failed |
overdue | The due date has passed without payment |
Billing dashboard metrics
The billing dashboard gives you a platform-wide snapshot of billing health viaBillingDashboardMetrics.
| Metric | Description |
|---|---|
total_tenants | Total number of tenants on the platform |
pending_invoices | Number of invoices currently in pending_payment status |
overdue_invoices | Number of invoices in overdue status |
monthly_revenue | Total revenue recognized in the current month |
The metrics displayed on the billing dashboard reflect the current state of all tenants across the platform, not just those visible on the current page.
Set up billing for a tenant
Open the tenant
Go to Tenants in the sidebar and click on the tenant you want to configure billing for.
Enter the billing amount and currency
Set
flat_rate_amount to the amount you charge this tenant each period. Set currency to the appropriate currency code.Choose billing frequency and day
Select
monthly or annually for billing_frequency. Set billing_day_of_month to the day invoices should be generated (for example, 1 for the first of each month).Set payment terms
Enter a value for
payment_due_days to define how many days the tenant has to pay before an invoice becomes overdue.Configure the billing email
Enter the email address in
billing_email that should receive invoice copies and payment reminders. Toggle email_notifications on to enable automatic email delivery.Enable automatic invoice generation
Set
auto_generate_invoices to true if you want the platform to create invoices automatically each billing period. Set it to false if you prefer to generate invoices manually.View invoice history
To review all invoices for a specific tenant:- Open the tenant from the Tenants list.
- Select the Billing tab.
- Scroll to the Invoice history section.
paid_date, payment_reference, and payment_method.
Monitor platform-wide billing
To view the billing metrics dashboard, go to Administration → Billing in the sidebar. The dashboard showstotal_tenants, pending_invoices, overdue_invoices, and monthly_revenue for the entire platform.