Billing overview#

Commercial billing on this platform is built around one idea: an agreement is a contract with a price, and separately a list of features the client is entitled to. The two never bleed into each other. A ₹0 discount, a changed price, or an extra line item never silently unlocks a feature — only the agreement's entitlements do.

This page is the map. Follow the links for the detail.

Who this is for#

Super Admins who run client contracts and collections.

• Difficulty: Easy
• Time: 5 min
• Prerequisites: Super Admin access.

Where everything lives#

All commercial billing screens are in the Super Admin Billing group:

The counting cards (/super-admin/billing/commercial)#

Click a card to drill through to the matching filtered Agreements list, so the list shows exactly what the card counted.

The three concepts, kept separate#

1. Price — the agreement wizard's line items, discount and tax. This is money only.
2. Entitlements — the features and limits ticked on the Services step. These (and only these) decide what the client can use.
3. Lifecycle state — Draft → Awaiting your approval → AutoPay setup pending → Active → Payment failed → Grace period → Past due → Restricted → Suspended (and Cancelled / Expired). This decides what the client can reach, not what they paid.

How money actually flows#

1. You create an agreement and send it to the client.
2. The client approves it in their portal, then authorizes AutoPay at the provider.
3. The platform verifies that authorization with the provider (a redirect alone never activates anything).
4. Renewals generate an invoice daily (06:30) and the provider debits the client.
5. Provider webhooks confirm each event; failures start the grace → restriction chain.

The single invariant worth remembering: the provider debits exactly the renewal invoice total, which is exactly the agreement's recurring gross amount.

Expected result#

You know which screen to open for any billing task, and you never confuse price, features and status.

Common mistakes#

• Looking for invoices under /super-admin/billing. The commercial invoice list is /super-admin/billing/commercial-invoices.
• Editing a price to grant a feature. Features are entitlements, not amounts.
• Treating the Overview dashboard as real-time collections. It is a metrics view; reconciliations run every 30 minutes.
• Forgetting the client portal side. Most confusion comes from not seeing what the client sees — open Client billing portal.

Troubleshooting#

Technical details#

• Pages: App\Filament\SuperAdmin\Pages\Commercial\{BillingOverview, CommercialInvoices, CommercialPayments, CommercialChangeRequests, CommercialProviders}; legacy metrics page App\Filament\SuperAdmin\Pages\Billing (/super-admin/billing).
• Tables: commercial_* (12 tables) + billing_invoices — the invoice table is not named invoices.
• Services: App\Services\CommercialBilling\* — BillingService, BillingCalculator, EntitlementService, InvoiceService, BillingChangeService, BillingNotifier, CommercialProviderManager.
• Lifecycle jobs: CreateRenewalInvoice 06:30, CheckUpcomingRenewals 07:00, CheckPaymentFailures hourly, ApplyGracePeriod 07:15, ApplyRestriction 07:30, ReconcileProviderStatus + SyncAppliedChangeRequests every 30 min.
• Entitlements gate: EntitlementService::has(); RESTRICTED allows only crm, lead_management, followups, reports; SUSPENDED denies everything.

Related guides#

• Commercial agreements
• Invoices & payments
• Payment providers (Razorpay / Cashfree)
• Payment failures & restrictions
• Client billing portal
• How billing & renewals work