# Billing and Invoices

## Overview

This journey covers how customers view and manage their billing information in the portal. All billing data (invoices, payment methods, billing summary) comes from WHMCS -- the portal reads it but does not store it locally. Customers can browse invoices, filter and search them, view full invoice details, download PDF copies, and pay unpaid invoices through a secure WHMCS link.

## Portal Flow

### Viewing the Invoice List

1. Navigate to **Account > Billing > Invoices** (URL: `/account/billing/invoices`).
2. The page loads with the title "Invoices" and a subtitle "Manage and view your billing invoices."
3. At the top, a **summary statistics bar** shows counts for:
   - **Total** invoices
   - **Paid** invoices (green)
   - **Unpaid** invoices (amber) -- only shown when count is greater than zero
   - **Overdue** invoices (amber) -- only shown when count is greater than zero
4. Below the stats bar, a **search and filter bar** lets you:
   - **Search** by invoice number or description (free-text search box)
   - **Filter by status**: All Statuses, Paid, Unpaid, Cancelled, Overdue, or Collections
   - A **Clear Filters** button appears when any filter is active
5. The invoice table shows each invoice in a row with: invoice number, description, status badge, total amount, due date, and issued date.
6. **Pagination** controls appear at the bottom of the table when there are more invoices than fit on one page (default 10 per page).

### Invoice Status Badges

Invoices display color-coded status badges:

| Status      | Color | Meaning                              |
| ----------- | ----- | ------------------------------------ |
| Paid        | Green | Invoice has been fully paid          |
| Unpaid      | Amber | Payment is due but not yet overdue   |
| Overdue     | Red   | Payment is past the due date         |
| Draft       | Grey  | Invoice is in draft, not yet issued  |
| Pending     | Amber | Invoice is pending                   |
| Cancelled   | Grey  | Invoice was cancelled                |
| Refunded    | Blue  | Invoice was refunded                 |
| Collections | Red   | Invoice has been sent to collections |

### Viewing Invoice Details

1. Click any invoice row in the list to open the invoice detail page.
2. The detail page shows:
   - **Summary bar** at the top with: total amount (large, bold), currency code, status badge, due date, days overdue (shown only for overdue invoices), invoice number, and issued date.
   - **Download PDF** button -- generates a secure WHMCS link and downloads the invoice as a PDF.
   - **Pay Now** button -- appears only for Unpaid or Overdue invoices. Opens the WHMCS payment page in a new browser tab.
   - If the invoice is **Paid**, a green "Payment received" banner appears showing the paid date.
3. Below the summary bar, the **line items** section lists each item on the invoice: description, item type, and amount.
4. At the bottom, the **totals section** shows subtotal, tax, and total.

### Downloading an Invoice PDF

1. From the invoice detail page, click **Download PDF**.
2. The portal generates a secure single-sign-on (SSO) link to the WHMCS invoice page.
3. The browser starts downloading the PDF. The customer does not need to log in to WHMCS separately.

### Paying an Invoice

1. From the invoice detail page for an Unpaid or Overdue invoice, click **Pay Now**.
2. The portal generates a secure SSO link to the WHMCS payment page.
3. A new browser tab opens with the WHMCS payment page, where the customer can complete payment using their saved payment methods.
4. For overdue invoices, a warning message reads: "This invoice is overdue. Please pay as soon as possible to avoid service interruption."

### Managing Payment Methods

1. Payment methods are stored in WHMCS (typically via Stripe).
2. From the invoice detail page, a **Manage Payment Methods** button opens the WHMCS payment methods page via SSO link.
3. Customers can add, update, or remove payment methods directly in WHMCS.

### Billing Summary on Dashboard

1. The customer dashboard shows a **Billing Summary** card with:
   - **Outstanding** amount and count of unpaid invoices
   - **Overdue** amount and count of overdue invoices
   - **Paid This Period** amount and count of paid invoices
   - A **View All** link to the full invoices page.

## What Happens in WHMCS

- **Invoices**: All invoices are stored in WHMCS under the Client's account. Navigate to **Clients > [Client Name] > Invoices** in WHMCS admin.
- **Invoice statuses**: WHMCS manages the status lifecycle (Draft, Unpaid, Paid, Overdue, Cancelled, Refunded, Collections). The portal reads these statuses directly.
- **Transactions**: When a customer pays an invoice, a Transaction record is created in WHMCS. You can find these under **Billing > Transactions** or under the specific Invoice in WHMCS admin.
- **Payment Methods**: Stored under **Clients > [Client Name] > Pay Methods** in WHMCS admin. These are typically Stripe-linked card details.
- **SSO Links**: The portal generates temporary WHMCS SSO links so the customer can view/download/pay invoices without needing separate WHMCS login credentials. These links expire after a short time.

## What Happens in Salesforce

- Salesforce is **not** the system of record for billing data. Invoices and payments live entirely in WHMCS.
- Salesforce receives **address snapshots** only when orders are created, so order records show the billing address used at checkout time.

## Key Things to Verify

- **Invoice list loads correctly**: Invoices appear sorted by date. Summary stats (total, paid, unpaid, overdue counts) match what you see in WHMCS admin.
- **Filtering works**: Selecting a status filter (e.g., "Unpaid") shows only invoices with that status. Search by invoice number returns the correct invoice.
- **Invoice detail matches WHMCS**: The total amount, line items, tax, due date, and status on the detail page all match the invoice in WHMCS admin.
- **PDF download works**: Clicking "Download PDF" downloads a valid PDF of the invoice.
- **Pay Now opens WHMCS**: Clicking "Pay Now" opens a new tab with the WHMCS payment page. The customer is already logged in (SSO). After payment, returning to the portal and refreshing shows the invoice as Paid.
- **Status badges are accurate**: A Paid invoice shows green, Unpaid shows amber, Overdue shows red.
- **Pagination**: If the customer has more than 10 invoices, pagination controls appear and navigate correctly.
- **Error handling**: If WHMCS is unavailable, the portal shows a friendly error message rather than broken or partial data.
- **Dashboard billing summary**: The billing summary card on the dashboard matches the overall totals from the invoices page.