102 lines
6.6 KiB
Markdown
102 lines
6.6 KiB
Markdown
# 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.
|