# Billing & Finance

## Overview

The Billing & Finance area is where you, the platform owner, watch the money. It pulls together five screens, all built from the same set of orders, so every payment a workspace makes — whether through Stripe, Razorpay, PayPal, or any of the 30+ gateways — rolls up into the same numbers.

Screen | Where to find it | What it answers
--- | --- | ---
Financial | Admin → Financial | "How is revenue trending right now?" MRR, ARR, refunds, outstanding.
Premium | Admin → Premium | "Which plans drive the business?" Plan mix, average revenue per customer, conversion.
Billing History | Admin → Billing History | "Show me every payment event." Charges, refunds, failures.
Order History | Admin → Order History | "How are subscriptions moving?" New, add-on, cancel, cohorts.
Invoices | Admin → Invoices | "Give me the document." Per-order invoice list and printable invoice.

> One source of truth: Every order has a status (paid, pending, failed, or refunded), the gateway it was paid through, the plan it was for (blank for credit or add-on purchases), and the date it was paid. The dashboards simply slice these orders by date window and status — so the same payment is never counted twice across screens.

## The Window Picker & How Deltas Work

Every dashboard has a date-window dropdown in the top-right. Changing it reloads the page with the new range applied to every KPI, chart, and table on that screen.

Screen | Window options | Default
--- | --- | ---
Financial & Premium | Last 7 days, 30 days, 90 days, last year | 30 days
Billing History | Last 7 days, 30 days, 90 days, last year, all time | 90 days
Order History | Last 90 days, this year, all time | 90 days
Invoices | This month, last month, this quarter, this year | This month

Wherever you see a small percentage chip on a metric (for example the green or coral chip under Gross revenue), it compares the current window against the window of the same length just before it. So "Last 30 days" is measured against the 30 days before that. An increase shows in green, a drop in coral.

> Tip: Because the comparison period scales with your selection, switching to a longer window smooths out day-to-day noise. Use 7 days to spot a sudden gateway outage, and 90 days or last-year to read the real trend.

## Financial Dashboard

The Financial dashboard (Admin → Financial) is your revenue control centre. The header lets you jump straight to Invoices or Order history.

### The Five KPI Cards

KPI | How it's calculated
--- | ---
Revenue (window) | The total of all paid orders within the window. Carries a change chip vs the previous period.
MRR (active) | A live snapshot — the total monthly price of every workspace currently on a paid, active plan. This is a "right now" figure, not tied to the window.
ARR (projected) | MRR × 12. A simple annual run-rate projection.
Refunds | The total of orders refunded in the window (dated by when they were refunded).
Outstanding | The total of orders still awaiting payment that were created in the window — money you've invoiced but not yet collected.

> Note on MRR: MRR counts each workspace's current plan price regardless of when it last paid, so it reflects your active subscription base. Revenue (window), by contrast, only counts money that actually came in during the window. The two will differ, and that's expected — one is a snapshot, the other is a flow.

### Charts & Tables

- Revenue over time — a daily chart of paid-order revenue across the window, with the window total printed in the header.
- Payment methods — a donut showing each gateway's share of paid revenue.
- Top paying workspaces — the ten highest-spending workspaces in the window, with order count and total spend. Each row links to that workspace's detail page.
- Order status — a donut of order counts by status (paid / pending / failed / refunded) for the window.
- Recent orders — the last eight orders platform-wide, with order number, workspace, plan, amount, status badge, and how long ago it happened.

## Premium Dashboard

Where Financial tracks cash, the Premium dashboard (Admin → Premium) tracks the subscription base itself — who's on what plan and how well you turn free customers into paying ones. The header links to the Packages manager and a "New plan" shortcut.

### The Four KPI Cards

KPI | How it's calculated
--- | ---
Paid workspaces | Number of workspaces on a paid plan.
Free workspaces | Everyone else — total workspaces minus paid. Your upgrade target.
ARPU | Average revenue per paid workspace = MRR ÷ number of paid workspaces.
Trial → paid | Conversion rate = workspaces that paid in the window ÷ new sign-ups in the window. Carries a change chip vs the previous period.

### Charts & the Plan Table

- Plan distribution — a donut of how many workspaces sit on each plan (free workspaces show as "Free").
- Revenue by plan — a bar chart of window revenue contributed per plan.
- New paid signups — a daily area chart of workspaces moving onto a paid plan.
- Most popular plans — the top five plans by order count over the trailing 90 days (this panel is fixed at 90 days regardless of the window picker).
- All plans table — every package with its price, billing duration, current workspace count, MRR contribution (price × workspaces), window revenue, and an active/off badge. Each row has an Edit link straight into the package editor.

> Tip: Read the All-plans table together with the donut. A plan with many workspaces but low MRR is a candidate for a price review; a plan with few workspaces but high revenue is your enterprise anchor — protect it.

## Billing History

Billing History (Admin → Billing History) is the payment record — every charge, refund, and failure the platform has processed. It has two views: the main list and an Analytics view, reached from the Analytics button in the header.

### KPI Strip

Five cards summarise the window:

KPI | Meaning
--- | ---
Gross revenue | Total paid in the window, with a change chip vs the previous period.
Successful charges | Number of paid orders, plus a success rate (paid ÷ paid + failed).
Failed | Number of failed orders — the payments worth chasing or retrying.
Refunds issued | Refund count with the total refunded amount.
Chargebacks | Shown for completeness; disputes aren't tracked yet, so this reads zero. The label stays in place for when disputes are added later.

### Auto-Bucketed Trend Chart

The Daily charges & refunds chart adapts its bucket size to the window length so the X-axis never gets crowded:

Window length | Bucket
--- | ---
Up to 31 days | Daily
Up to 100 days | Weekly (Monday-anchored)
Up to ~400 days | Monthly
Beyond that (all time) | Quarterly

Charges plot in deep green and refunds in coral. The Analytics view adds a third failed series in amber.

### Filtering the List

Below the trend chart sit the filters. They combine, and they keep the window you've chosen:

- Status pills — All, Successful, Failed, Refunded, Pending.
- Gateway dropdown — narrow to a single payment provider (only the gateways actually used in your orders appear).
- Search box — matches order number, customer name, customer email, or workspace name.

The list shows 12 events per page with date and time, order number, workspace (and customer email), gateway, plan, amount (refunds shown as negative, in the order's own currency), and a colour-coded status badge. Failed and refunded rows have a tinted background so they're easy to spot. The arrow at the end of each row opens that workspace.

### Billing Analytics

The Analytics view widens the picture with a six-card strip and richer breakdowns:

KPI | Meaning
--- | ---
Gross revenue | Paid total, with a change chip vs the previous period.
Net revenue | Gross minus refunds, plus the percentage you kept.
Payment success | Success rate with the paid / total-attempts count.
Failed | Failed amount and number of events.
Refunds | Refunded amount and number of events.
Chargebacks | Placeholder (zero) until disputes are tracked.

Below the cards: a cash-flow trend showing charges, refunds, and failures together; a Gateway share donut splitting paid revenue by provider; the Top paying workspaces table; and an Order status mix donut.

## Order History

Order History (Admin → Order History) looks at the same orders from a subscription angle — new business, add-ons, and cancellations — rather than raw payments. Like Billing History, it has a main list and an Analytics view.

### Order Types

Order History gives each order a "type" label based on its status and whether it includes a plan, so you can filter the list by what the order was for:

Type / badge | What it means
--- | ---
New / Renewal | A paid order. "New" when no plan is attached, "Renewal" when a plan is attached.
Add-on | A paid order with no plan attached — typically a credit top-up or one-off purchase.
Pending | An order awaiting payment.
Cancel | A failed or refunded order — lost revenue.

The filter pills (All, New, Upgrade, Downgrade, Add-on, Cancel) match these types, and the search box matches order number, customer email, or workspace name. Results show 12 per page.

### KPI Strip

Six cards: Total orders (with a period-over-period change), Upgrades (paid count, plus MRR added), Downgrades (a placeholder — downgrades aren't tracked yet), Add-ons (count and value), and Cancels (count and MRR lost).

### Order Analytics

The Analytics view is the most detailed of the finance screens.

- Headline KPIs — Total orders, Net new MRR, Lost MRR, Average order value (paid total ÷ paid count), Add-on attach rate (add-ons as a % of all orders), and Conversion rate (paid ÷ sign-ups).
- Daily order motion — a chart (same daily/weekly/monthly/quarterly grouping as Billing History) plotting new orders against cancels.
- Order type mix — a donut and counters splitting Renewal / Add-on / Cancel.
- Add-ons sold — the top non-plan items by spend, as ranked bars.
- Conversion funnel — Pricing-page visits → Sign-ups → Trials started → Active in trial → Converted to paid.
- By country — top markets by paid-order count. This panel is illustrative: the platform doesn't store a country for each user, so it stays empty in practice.
- Cohort retention — a heat-map of the last six monthly sign-up groups, showing the percentage of each group still subscribed at months 0 through 5.

> Read these as directional, not exact: A few items above — the top funnel stages (visits, trials, active-in-trial) and the downgrade KPI — use rough estimates, because the platform doesn't yet track page visits or downgrade events. The lower funnel (sign-ups, conversions), cohort retention, average order value, and all revenue figures come from real order data and are accurate. Treat the top of the funnel as a trend, not a precise count.

## Invoices

The Invoices screen (Admin → Invoices) turns each order into a billing document. Every paid or pending order gets an invoice with a number based on its order number (shown in the list as `INV-...`).

### Invoice KPI Strip

KPI | Meaning
--- | ---
Total invoices | All-time invoice count.
Paid | Paid count plus the paid percentage.
Outstanding | Pending invoice count and the total amount due.
Overdue | Pending invoices created more than 15 days ago.
This month | This month's paid total, with a month-over-month delta.

### Invoice List & Status

Filter with the status pills — All, Paid, Outstanding, Overdue, Refunded, Void — plus the window dropdown (this/last month, this quarter, this year) and a search box (invoice number, workspace, owner). The status badge is derived from the order:

Order status | Invoice badge
--- | ---
Paid | paid (green)
Pending, 15 days old or less | outstanding (amber)
Pending, more than 15 days old | overdue (coral, with days-late count)
Refunded | refunded (purple, amount shown negative)
Failed | void (grey)

Each row shows the invoice number, issue date, due date (with a late marker when overdue), workspace and owner, the plan or "Add-on" item, the amount in its own currency, the status badge, a view-invoice icon, and a per-row actions menu.

### The Single Invoice View

Clicking an invoice opens a clean, printable document. It is laid out as a real tax invoice:

- An admin-only status banner at the top (hidden when printing) summarising amount, gateway, and payment reference.
- Your company header — logo, address, and tax ID — drawn from the platform billing settings.
- A Bill to block (billing company / customer / workspace name, email, and address) and a Payment block (method, transaction ID, captured-at time, currency, and coupon code if one was used).
- Line items with subtotal, any coupon discount (shown negative), tax line (label and rate from your settings), total, amount paid, and balance due.
- Footer notes and a "Need help?" block with your billing email and phone.

The Print and Download PDF buttons both trigger the browser's print dialog, so you can hand a customer a PDF without any extra tooling.

> Set your invoice identity once: The company name, address, tax ID, tax label/rate, and support contact on every invoice come from the platform billing settings. Fill those in under System Settings before sending the first invoice so customers see your brand, not a placeholder.

## Related Pages

- Plans & Packages — build the tiers whose prices feed MRR and the plan tables.
- Payment Gateways — the providers behind the gateway donuts and the ledger.
- Coupons & Credits — the discounts and credit bundles that appear on invoices and as add-on orders.
- Workspaces — the detail page every "top paying workspace" row links to.