Skip to Content
Ranlanka CRM documentation — pre-release, subject to change.
FeaturesFinance & Invoicing

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 final Total 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/week or LKR 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.
  • 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, and Remaining Balance directly 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 From block 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.
  • Overdue Passport Custody Notice in Invoice Modals: When an invoice or any linked booking request is associated with an approved or rejected visa 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 a Passport 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 to 0.00, and status is set to PAID.
  • Zero-Paid Invoices: If no payments were collected, a 100% waiver line is applied, reducing the net total to 0.00 with status PAID, 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, or paid) 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.
Last updated on