Finance & Invoicing
Issuing invoices
Staff issue invoices directly from a visa/ticket case (once it reaches an eligible stage) — invoicing doesn’t require a prior quotation, but shares the same admin pricing templates when one applies.
Visa invoices auto-populate their line items from the matching pricing template; each item is editable before submitting. Ticket invoices have no pricing template to auto-fill from, but are itemized the same way — staff get a single editable “Ticket Price” row to start (not locked, since there’s no catalog price behind it) and can add further custom charges (baggage, seat selection, service fees, etc.) via the same “Add Custom Field” control visa invoices use. Every added row shows up individually on the invoice PDF and the staff-facing invoice detail view, exactly like visa’s line items do.
Permissions: consultants (not just owners/cashiers) can create, view, and generate PDFs for their own customers’ invoices day to day. Cancelling an invoice remains owner/manager-only.
Cost Amount (what the agency actually paid out for the service) applies to every service type except visa — ticket/flight and tour invoices both collect it (tour invoices collect it regardless of whether the tour used a priced template or was manually itemized), and it’s used to work out profit margin. It’s hidden on visa invoices entirely and defaults to 0 server side — visa profit is worked out from the Consulting Fee line item instead, see Accounting: how Profit is calculated. Staff can see an invoice’s Cost of Sale and Profit in an internal-only box on its detail view (never shown to the customer, never printed on the PDF) whenever a cost was recorded.
Group (dependent) invoicing
When several requests share a booking group — a family applying together, for example — staff can issue one invoice covering the whole group instead of one per request. Each request keeps its own line-item section and subtotal within the single invoice/PDF.
Itemized tax & discount
Tax and discount are repeatable line items, not a single amount each — for example “VAT” and “Service Charge” as separate tax rows, each with an optional note. The invoice’s stored totals are always the sum of these rows, computed server-side and never trusted from the client. Both the invoice detail view and the downloaded PDF show every row individually.
Invoices vs. receipts
The invoice PDF and the payment-receipt PDF are separate documents branded under “Ranlanka Travel & Visa Consultancy Services”:
- Invoice PDF (
invoice-template.html/InvoicePdfService) — Strictly presents billed service charges, itemized tax/discount rows, and the finalTotal Amount ({{CURRENCY}}). Payment status badges (UNPAID/PARTIAL/PAID),Amount Paid,Balance Due, and exchange rate conversion rows are deliberately omitted from the invoice so it remains a pure billing statement:- Customer Identification (
Bill To): Renders the customer’s full name, email, phone, NIC / Passport, and residential address when available on file. - Statutory Fee Classification Sub-Notes: Automatically annotates standard line items (
Visa Fee$\rightarrow$ Statutory Consular / Embassy Disbursement (Pass-Through);Consulting Fee$\rightarrow$ Agency Facilitation & Professional Handling Fee; custody/holding fee rows $\rightarrow$ Overdue Passport Safe Vault Custody Charge (> 7 Days)). - 7-Point Regulatory & PDPA Disclosures: Embeds standard terms covering consular disbursement non-refundability, the 7-day passport safe custody policy (
LKR 500/weekorLKR 100/day), 30/60-day unclaimed document protocol, and Sri Lanka PDPA Act No. 9 of 2022 compliance. - Commented-Out Statutory & Bank Placeholders: Includes ready-to-uncomment HTML/Java blocks for Business Registration (BR No.), TIN, VAT/SSCL, SLTDA/CAASL license numbers, and corporate bank transfer coordinates.
- Customer Identification (
- Receipt PDF (
receipt-template.html/ReceiptPdfService) — Official payment history and settlement statement, generatable once at least one payment has been recorded:- Direct Invoiced Currency: Displays all payment amounts,
Total Paid, andRemaining Balancedirectly in the invoice’s currency ({{CURRENCY}}/{{CURRENCY_NAME}}, e.g.,LKR) without currency conversion rows. - Customer Identification & Payment Notes: Includes customer NIC / Passport and Address in the
Received Fromblock and renders per-receipt payment notes under each payment entry. - 4-Point Receipt Disclosures: Covers cheque realization, non-refundable consular/carrier disbursements, 7-day passport collection policy, and PDPA data retention.
- Direct Invoiced Currency: Displays all payment amounts,
- Overdue Passport Custody Notice in Invoice Modals: When an invoice or any linked booking request is associated with an
approvedorrejectedvisa that has remained uncollected for more than 7 days (isPassportCustodyOverdue = true), both<InvoiceDetailModal />and<EditInvoiceModal />display an amber Overdue Passport Custody Notice showing the exact days held and days overdue, prompting admins to add aPassport Vault Custody Fee(LKR 500/week) via Edit Invoice.
The receipt/payment-history section in the invoice detail view is collapsed by default and hidden entirely until a payment exists.
Emailing documents
Invoices and receipts can be emailed directly to the customer as a PDF attachment from the invoice detail view — no download-then-manually-send workflow required.
Invoice Cancellation (Hard Delete)
Cancelling an invoice (POST /api/v1/invoices/{id}/cancel) is an owner/manager action that permanently purges the invoice, its line items, tax lines, discount lines, request links, and all recorded payments/receipts from the database. This guarantees that cancelled or mistakenly created invoices cannot distort sales figures, cash flow summaries, or monthly digests.
Rejected Visa Settlement & Balance Waiver
When a visa application is rejected by the embassy, staff can settle the linked invoice (POST /api/v1/invoices/{id}/settle-rejection):
- Debt Waiver: Automatically creates a
"Visa Rejection Balance Waiver"discount line for the uncollectible balance. - Revenue Matching: The invoice total is adjusted to match collected revenue (
amountPaid), outstanding balance is cleared to0.00, and status is set toPAID. - Zero-Paid Invoices: If no payments were collected, a 100% waiver line is applied, reducing the net total to
0.00with statusPAID, keeping the audit trail clear.
Admin-Only Invoice Editing
Invoices can be updated after issuance by administrators (PUT /api/v1/invoices/{id}), restricted to owner and manager roles with INVOICE_EDIT permission:
- Modifiable Line Items, Charges & Discounts: Admins can edit descriptions, add custom fees (such as late charges, flight rebooking penalties, or luggage supplements), adjust itemized taxes, add/edit discount lines, and revise direct cost amounts.
- Strict Ledger Invariant: The updated net total (
subtotal + taxAmount - discountAmount) cannot be reduced below the amount already collected in payment receipts (amountPaid). This prevents accounting ledger corruption and negative uncollectible balances. To lower an invoice total below paid receipts, receipts must first be cancelled/refunded. - Live Status & Finalization Recalculation: Invoice status is automatically re-evaluated (
unpaid,partial, orpaid) based on collected receipts against the new total, and linked flight/visa task finalization statuses are dynamically synchronized. - PDF Cache Invalidation: The cached PDF binary (
pdf_data) is automatically invalidated on update, ensuring any subsequent PDF download or customer email generates a fresh document reflecting the new charges.
Organized Invoice Action Bar
The <InvoiceDetailModal /> features a modern, structured two-tier action bar:
- Document & Export Toolbar: A clean, dedicated strip grouping Invoice (Download PDF / Email) and Receipt (Download PDF / Email) actions with clear type badges and intuitive Lucide icons.
- Operations & Management Bar: Cleanly segregates destructive actions (
Cancel & Delete,Settle on Rejection) on the left from management controls (Edit Invoice) and highlighted primary operational call-to-actions (Record Payment) on the right.
Customer Financial Breakdown & In-Page Detail Drawer
In the Services & Invoicing sub-tab under Visa, Ticket, and Tour statistics panels, admins can view an aggregated Customer Financial Breakdown Table:
- Server-Side Aggregation & Filtering: Data is aggregated at the PostgreSQL database level using high-performance CTE queries and paginated server-side to handle large customer volume efficiently.
- Status Tabs: Easily filter customer records by overall payment status (
All,Fully Paid,Partially Paid,Unpaid,Not Invoiced). - In-Page Customer Detail Drawer: Clicking on any customer name, invoiced count badge, or action button opens a slide-over
<CustomerServiceDetailDrawer />right inside the financial panel.- Financial Summary: Shows total invoiced, total paid, and outstanding balance for that customer.
- Essential Ticket / Request Details: Displays PNR, airline, ticket number, price, visa application status, and appointment dates.
- Invoice & Payment Actions: Allows downloading Invoice PDF, Receipt PDF, and recording payments directly via
<RecordPaymentModal />without navigating away from the finance panel.