Assist_Design/docs/uat/09-billing-and-invoices.md

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.