Navigation
14.17. Preview, Validate, and Troubleshoot Invoice Layouts
Use preview, sample data, existing invoices, and validation checks to troubleshoot custom invoice layouts before they reach clients.
14.17. Preview, Validate, and Troubleshoot Invoice Layouts
Use preview, sample data, existing invoices, and validation checks to troubleshoot custom invoice layouts before they reach clients.
14. Billing and ContractsUpdated: 5/3/2026
Preview and validation are the safety net for invoice layouts. They help billing admins catch missing fields, layout overlap, transform mistakes, and PDF rendering issues before clients see the invoice.
Figure 1: The Preview tab renders the layout and shows whether the layout shape and render steps succeeded.
Preview sources
| Source | Use it for |
|---|---|
| Sample data | Fast checks while building the layout. Good for early design work. |
| Existing invoice | Final review using real invoice complexity, client data, taxes, and line items. |
Start with sample data, then test with an existing invoice before assigning the layout to production billing.
What to validate
| Area | What to check |
|---|---|
| Header | Logo, MSP name, invoice number, issue date, due date, and client name. |
| Billing details | Customer address, PO number, service period, and any required client reference. |
| Line items | Descriptions, quantities, rates, amounts, service periods, and wrapping. |
| Totals | Subtotal, tax, discounts, credits, and final total. |
| Styling | Colors, spacing, alignment, borders, and readability. |
| PDF fit | Page size, margins, table length, footer placement, and no overlap. |
| Data rules | Filters, sorts, groups, and totals match billing expectations. |
Common troubleshooting issues
| Symptom | What to check |
|---|---|
| A field is blank | Confirm the invoice actually has that value and the correct field is used. |
| Line items do not appear | Check the line-item table binding and preview with an invoice that has billable lines. |
| Totals look wrong | Confirm the totals component is bound to invoice totals and that custom transforms are not excluding rows. |
| Text overlaps | Increase component width or height, adjust container spacing, or reduce font size. |
| Table columns are cramped | Widen the table, reduce optional columns, or shorten column labels. |
| Logo is distorted | Adjust image size and preserve the expected aspect ratio. |
| Preview works with sample data but not an existing invoice | Compare the sample structure to the existing invoice; check optional fields, long descriptions, taxes, and line-item counts. |
| PDF cuts off content | Review paper preset, margins, component placement, and long dynamic tables. |
Safe rollout process
- Build or edit the layout as a draft.
- Preview with sample data.
- Preview with at least one simple existing invoice.
- Preview with one detailed invoice that includes multiple line items, tax, and service period data.
- Ask billing staff to review the PDF as the client would see it.
- Assign the layout to a narrow scope first when possible.
- Monitor the first invoices generated with the new layout.
When to pause and revise
Do not use a layout for client billing if:
- invoice number, client name, due date, or total is missing;
- line items are hidden or unreadable;
- totals do not match the invoice;
- client-specific wording appears in a general default;
- PDF output cuts off content;
- billing staff cannot explain why a transform or grouping rule exists.
A layout should make billing clearer. If it creates confusion during preview, simplify it before assigning it.