> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Billing operations
> Issue refunds, apply credits, create invoices, monitor payment failures, and review purchase orders from the billing operations console.
The billing operations console gives billing administrators a single page to manage financial operations across all tenants. Navigate to **Billing > Billing Operations** in the platform console.
The billing operations console is available to users with the **billing admin** or **super admin** [platform role](/guides/platform-staff).
## Overview
The operations hub links to five tools:
| Tool | What it does |
| :------------------------- | :------------------------------------------------------- |
| **Refunds** | Issue partial or full refunds across payment providers |
| **Credits** | Apply manual credits and adjustments to tenant accounts |
| **Manual invoices** | Create and track offline invoices for enterprise tenants |
| **Failures & suspensions** | Monitor payment failures and suspended accounts |
| **PO review** | Review and approve enterprise purchase orders |
## Issuing refunds
Navigate to **Billing > Operations > Refunds** to issue a refund.
Provide the **Tenant ID**, select the **payment provider** (Stripe, Paystack, or Flutterwave), enter the **Charge ID** from the provider, and the **refund amount** in dollars.
Click **Issue Refund** to open the confirmation dialog. Enter a reason for the refund — this is recorded in the audit log.
The refund is submitted to the payment provider. The tenant and amount are logged for billing reconciliation.
You can issue partial refunds by entering an amount less than the original charge. The charge ID is available from the provider's dashboard or from the tenant's invoice history.
## Applying credits
Navigate to **Billing > Operations > Credits** to apply a manual credit.
Provide the **Tenant ID** and the **credit amount** in dollars. Click **Issue Credit** and enter a reason. Credits are applied in USD and tracked in the tenant's billing ledger.
Use credits for:
* Goodwill adjustments after a service disruption
* Promotional offers or onboarding incentives
* Correcting billing errors
## Creating manual invoices
Navigate to **Billing > Operations > Manual Invoices** to create an offline invoice for tenants that pay outside the standard billing flow — for example, government agencies or enterprises using wire transfers.
## Monitoring payment failures
Navigate to **Billing > Operations > Failures & Suspensions** to view tenants with failed payments or suspended accounts. This page surfaces accounts that are progressing through the [payment failure lifecycle](/billing/overview#payment-failures-and-grace-periods) so you can intervene before access is fully suspended.
## Reviewing purchase orders
Navigate to **Billing > Operations > PO Review** to manage enterprise purchase orders.
The review queue shows submitted POs with their amount, status, and submission date. Approve a PO to activate billing against the order balance, or reject it with a reason that is sent back to the submitting tenant.
For details on how tenants submit purchase orders, see [purchase order billing](/billing/overview#purchase-order-billing).
## Tenant billing monitoring
Navigate to **Billing > Tenants** to see a dashboard of billing health across all tenants.
The page shows:
* **MRR summary** — total monthly recurring revenue across all tenants.
* **Status breakdown** — counts of active, trial, past due, and canceled subscriptions.
* **Tenant table** — each row shows the tenant name, plan, subscription status, payment provider, last payment date, and MRR contribution.
Click any row to open the tenant billing detail page, which shows the tenant's subscription, entitlement quotas, recent invoices, and admin action controls.
### Dunning overrides
When a tenant's payment fails, the billing system moves them through a graduated dunning lifecycle (degraded, restricted, suspended). You can override this behavior from the tenant billing detail page.
Click **Override Dunning** to open the dunning override dialog. The dialog has four fields:
| Field | Description |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Contract mode** | Controls how the dunning lifecycle behaves for this tenant. See the table below. |
| **Force state** | Immediately set the tenant to a specific billing state. Leave as "No Change" to keep the current state. Options: `Active`, `Past Due`, `Unpaid`, `Suspended`. |
| **Grace extension (days)** | Add extra days to the tenant's grace period before the next dunning stage kicks in. |
| **Reason** | Required. A note explaining the override — for example, a support ticket number or billing dispute reference. |
#### Contract modes
| Mode | Behavior |
| :------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Standard (Auto)** | Default. The system automatically retries failed payments and progresses through dunning stages on a fixed schedule. |
| **Enterprise (Manual)** | Disables automatic retries. The tenant stays in their current state until a billing admin manually intervenes — useful for enterprise accounts that pay by wire or PO. |
| **Government (No Retry)** | No automatic retries. Designed for government procurement workflows where payment timelines are outside your control. |
Use dunning overrides when you need to:
* **Restore access** during a billing dispute by forcing the state back to `Active`
* **Extend a grace period** while waiting for a wire transfer by adding grace days
* **Switch to manual dunning** after signing an enterprise contract by changing the contract mode to Enterprise
* **Accommodate government procurement** timelines by switching to the Government mode, which prevents automatic suspension
Dunning overrides bypass the standard payment enforcement lifecycle. Every override requires a reason and is recorded in the audit log. Use the **Force State** option sparingly — it immediately changes the tenant's billing state regardless of payment status.
### Grace period controls
You can grant a temporary grace period that extends a tenant's access to a specific metric beyond their plan limit.
From the tenant billing detail page, click **Add Grace** to open the grace period dialog:
| Field | Description |
| :------------------- | :--------------------------------------------------------------------------------------------------------------- |
| **Metric** | The usage metric to extend. Available metrics: `Verifications`, `Mints`, `Webhook Endpoints`, `Storage (Bytes)`. |
| **Extra allowance** | Number of additional units to allow beyond the plan limit. |
| **Duration (hours)** | How long the grace period lasts before it expires automatically. |
#### Available metrics
| Metric | What it controls |
| :-------------------- | :------------------------------------------------------ |
| **Verifications** | Additional verification API calls beyond the plan quota |
| **Mints** | Additional attestation mints beyond the monthly limit |
| **Webhook Endpoints** | Extra webhook endpoint slots beyond the plan maximum |
| **Storage (Bytes)** | Additional storage capacity in bytes |
Active grace periods are listed below the controls with their metric name, extra allowance, and expiration date. Each grace period expires independently — you can have multiple active periods for different metrics at the same time.
Grace periods are useful for onboarding scenarios where a tenant needs temporary headroom while evaluating an upgrade. For permanent changes, use [entitlement overrides](#entitlement-overrides) instead.
### Entitlement overrides
Platform admins can set per-tenant feature flags and quota overrides that take precedence over the tenant's plan entitlements. Use this for custom agreements, pilot programs, or temporary access grants.
From the tenant billing detail page, open the **Override** dialog:
* **Quotas** — set numeric overrides for specific metrics (e.g. increase `attestations.mint` to 10,000 or set `seats` to 10).
* **Features** — toggle feature flags as a JSON object (e.g. `{"offline_bundles": true}` to enable a feature not included in the tenant's plan).
Overrides persist until you remove them. They do not expire with the billing cycle.
Entitlement overrides bypass plan-level enforcement. Use them sparingly and document the reason in the tenant's notes.
## Related
Plans, rate cards, entitlements, and payment failure lifecycle.
Create custom rate cards for partner tenants.
Per-tenant billing detail and subscription management.
Staff roles including billing admin permissions.