> ## Documentation Index
> Fetch the complete documentation index at: https://afrizon-admin.tunzaa.co.tz/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up billing and manage invoices for tenants

> Configure per-tenant billing settings, track invoice status from pending to paid, and monitor platform-wide revenue and overdue invoices in Meneja.

Meneja gives you a centralized place to configure how each tenant is billed, track invoice status, and monitor platform-wide billing health. The billing system ties together a per-tenant billing configuration, an invoice ledger, and a dashboard metrics view so you can quickly see what is owed, what is overdue, and what revenue the platform has generated.

## Billing configuration

Each tenant has one `BillingConfig` 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  |

<Note>
  `billing_frequency` accepts `monthly` or `annually`. The schema also supports `quarterly` as a valid value.
</Note>

## Invoices

Every billing cycle generates an `Invoice` 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 via `BillingDashboardMetrics`.

| 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            |

<Info>
  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.
</Info>

## Set up billing for a tenant

<Steps>
  <Step title="Open the tenant">
    Go to **Tenants** in the sidebar and click on the tenant you want to configure billing for.
  </Step>

  <Step title="Navigate to the Billing tab">
    Inside the tenant detail view, select the **Billing** tab.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Save the configuration">
    Click **Save**. The billing configuration becomes active immediately and will apply to the next billing cycle.
  </Step>
</Steps>

## View invoice history

To review all invoices for a specific tenant:

1. Open the tenant from the **Tenants** list.
2. Select the **Billing** tab.
3. Scroll to the **Invoice history** section.

The list shows each invoice's number, amount, status, issue date, and due date. Click an invoice to see the full detail including `paid_date`, `payment_reference`, and `payment_method`.

<Warning>
  Invoices with `overdue` status are not automatically resolved. You must manually update the status once payment is received, or use the external payment reference to reconcile against your payment processor records.
</Warning>

## Monitor platform-wide billing

To view the billing metrics dashboard, go to **Administration → Billing** in the sidebar. The dashboard shows `total_tenants`, `pending_invoices`, `overdue_invoices`, and `monthly_revenue` for the entire platform.

<Tip>
  Check the billing dashboard regularly to catch overdue invoices early. Reaching out to tenants before invoices are significantly overdue reduces the risk of service interruption.
</Tip>