10.1 Plain-English Accounting: What Happens When You Issue a Tax Invoice?

In Article #09, we learned that a Quotation or Pro-Forma Invoice is a commercial offer that does not touch your General Ledger or deduct physical stock. By contrast, a Tax Invoice (INV-) is a legally binding accounting and tax document.

The moment an invoice transitions from Draft to an active billing status (such as Sent, Partially Paid, or Paid), Keystone X automatically executes two simultaneous double-entry journal postings and one physical inventory movement behind the scenes:

10.2 The Revenue & Fulfillment Command Center (invoice/index)

Navigate to Sales & Receivables → Invoices (invoice/index) to open the Revenue, Invoicing & Delivery Fulfillment Command Center.

Top Header Action Bar & Workspace Switcher

The 4 Executive KPI Cards

Multi-Parameter Filter Ribbon

Below the KPI cards is a live server-side filter bar (GET /invoice/index) that persists across both the Ledger and Board views:

• Search Box (q): Searches by Invoice Number (INV-0001), Customer Name, or Customer Purchase Order Number.
• Lifecycle Stage (status): Filters by any custom stage configured in your Studio (e.g., Draft, Sent, Partially Paid, Paid, Overdue, Cancelled).
• Fulfillment (fulfillment): Filters by physical logistics state (Pending Dispatch, Packing / Ready, In Transit / Out for Delivery, Delivered / POD Signed, or Not Applicable (Service)).
• Date From (date_from) & Date To (date_to): Filters by Invoice Issue Date range, with a Filter submit button and a 1-click Reset (×) button.

10.3 Workspace 1: The Ledger View & Its 3 Internal Sub-Tabs

When viewing the Ledger (?view=list) workspace, a sub-navigation header provides three specialized operational tabs:

Sub-Tab A: Invoice Register (#ledger-all)

The complete master register of all Tax Invoices matching your active filters.

Sub-Tab B: Collections & Overdue (#ledger-overdue)

Automatically filters the ledger down to delinquent accounts (balance_due > 0 and due_date < today) so your Credit Controller can chase overdue cash immediately.

• Days Late Badge: Calculates exact calendar days overdue and color-codes severity (amber for 1–29 days late, red for 30+ days late).
• 1-Click Capture Payment Button: Opens invoice/preview/{id}#paymentModal to receipt an incoming EFT or apply customer wallet funds.
• 1-Click Send Reminder (Envelope Button): Fires an automated overdue dunning email (invoice/send/{id}) with the PDF attached directly to the client's billing contact.

Sub-Tab C: 12-Month Revenue Analytics (#ledger-analytics)

Presents an interactive Chart.js bar chart comparing Monthly Billed Revenue (Green) vs. Collected Cash (Blue) over the trailing 12 months, alongside a right-hand Lifecycle Breakdown card showing exact invoice counts and rand values sitting in every pipeline stage.

10.4 Workspace 2: The Revenue Pipeline Kanban Board (?view=board)

Click Board in the top-right workspace switcher to visualize your invoices as draggable cards arranged across columns representing each configured Lifecycle Stage (e.g., Draft → Sent → Partially Paid → Paid → Overdue).

• Column Headers: Show the stage dot color, stage name, total count of invoices in that stage, and the cumulative rand value of the column.
• Drag-and-Drop Stage Transitions: Dragging a card from one column to another immediately fires an AJAX call to invoice/updateStatusAjax, updating the invoice's status and recalculating column totals without reloading the page.
• Quick Card Footer Actions: Each Kanban card displays the due date, outstanding balance, an Eye icon (Open Cockpit), and a PDF icon (Download Tax Invoice PDF).

10.5 Workspace 3: The Dispatch Hub & Waybill Tracker (?view=delivery)

Click Dispatch Hub in the workspace switcher to open the dedicated logistics command center designed for your Warehouse Dispatchers, Drivers, and Fulfillment Coordinators.

10.6 Creating & Editing a Tax Invoice (invoice/add & invoice/edit)

Clicking + Create Invoice opens the comprehensive Tax Invoice & Fulfillment Builder (invoice/add). Every field is engineered to prevent billing errors, enforce customer credit limits, and automate due-date and tax math.

Part 1: Customer, Credit Governance & Commercial Metadata

Part 2: Delivery Fulfillment & Waybill Automation Panel

Directly beneath the commercial metadata is a dedicated blue-bordered Delivery Fulfillment & Waybill Automation card:

• Fulfillment Status (fulfillment_status): Set to Pending Dispatch, Packing / Ready, In Transit, Delivered / POD Signed, or Not Applicable (Service Only).
• Courier / Dispatch Method (delivery_method): Choose from your Studio-configured fleet/courier list (e.g., Company Fleet / Driver, Client Collection (Ex-Works), The Courier Guy, RAM Hand-to-Hand, Digital / Electronic Delivery).
• Tracking / Waybill Reference (tracking_number): Optional courier waybill reference.
• Auto-Generate Delivery Note (DN-) Toggle Switch (auto_create_delivery_note): Checked by default when creating a new invoice. When enabled, saving the Tax Invoice automatically generates a companion DN-XXXX Waybill for all physical line items (Automatically turns off if you select Service Only or Digital Delivery).

Part 3: Line Items, Serial Numbers & Tax Engine

The Invoice Line Items grid supports both catalog inventory items and free-text service lines:

• Item / Description (item_id[] + description[]): Selecting a catalog SKU automatically populates the Item Description, Selling Price, and Tax Rate. You can also choose -- Custom Item / Service -- to type an ad-hoc consulting or labor description.
• Serial Number Allocation Selector (serial_numbers[]): Whenever you select a catalog item that has Serial Number Tracking enabled (`track_serials = 1`), an interactive blue Select S/N... dropdown appears directly beneath the description, listing every available `in_stock` serial number in your warehouse. Selecting a serial number prints `S/N: XXXX` on both the Tax Invoice and Delivery Note PDFs and starts the customer's warranty clock.
• Qty (quantity[]) & Unit Price (unit_price[]): Multiplies quantity by unit price to calculate the row total.
• Tax Selector (tax_type[]): Choose between Standard 15% (STD), Zero-Rated 0% (ZERO), or Exempt 0% (EXM).
• Summary Footer (Subtotal, Discount, VAT & Grand Total): Supports an optional invoice-wide Discount Amount (discount_amount) which proportionally reduces the taxable base before calculating 15% Output VAT and the final Total Due.

Part 4: Attachments, Terms & Notes

• Supporting Documents (attachments[]): Upload signed client POs, job cards, or spec sheets (`PDF`, `JPG`, `PNG`, `DOCX`, `XLSX`) to attach to the invoice record.
• Terms & Conditions (terms): Rich-text editor pre-filled with your default Studio payment terms and late-interest clauses.
• Client Notes (notes_client): Visible to the customer on the Tax Invoice PDF.
• Internal Notes (notes_internal): Highlighted in amber with a lock icon; strictly private to staff and never printed on customer PDFs.

10.7 The 360° Invoice & Fulfillment Cockpit (invoice/preview/{id})

Clicking any invoice number opens the Invoice & Fulfillment Cockpit (invoice/preview/{id}), combining an interactive stage progression bar, a print-accurate Tax Invoice document preview, a multi-shipment Delivery Note manager, and a Credit Wallet-aware Payment Receipting engine.

1. Top Action Bar & Interactive Lifecycle Stepper

• Interactive Stage Stepper Bar: Displays every stage in your billing workflow as connected nodes. Clicking any stage node immediately transitions the invoice to that stage via AJAX (`updateStageFromCockpit()`).
• Dispatch / Waybill Button: Opens the Generate Delivery Note & Partial Shipment Modal (#createDeliveryNoteModal).
• Email Invoice Button: Dispatches the Tax Invoice PDF via email (`invoice/send/{id}`) to the customer.
• Tax Invoice PDF Button: Opens/downloads the official SARS-compliant Tax Invoice PDF (`invoice/pdf/{id}`).
• Record Payment Button: Appears whenever `balance_due > 0`. Opens the Record Payment & Wallet Modal (#paymentModal).
• Issue Credit Note Button: Appears on finalized (`Sent`, `Paid`, `Partially Paid`, `Overdue`) invoices. Jumps directly to `CreditNote/create/{id}` pre-loaded with this invoice's items for a financial reversal or stock return.

2. Partial Shipments & Split Delivery Notes (#createDeliveryNoteModal)

What if a customer orders 10 laptops on one Tax Invoice, but you only have 6 in stock today and 4 arriving next week?

Clicking Dispatch / Waybill inside the Invoice Cockpit opens an advanced modal that includes a Line Items to Include in This Shipment table. Next to each product row, you can adjust the Dispatch Qty (delivered_qty[]) from `10` down to `6` for the first Delivery Note (`DN-0019`), and then generate a second Delivery Note (`DN-0020`) for the remaining `4` units next week!

3. Capturing Payments & 1-Click Credit Wallet Settlement (#paymentModal)

Clicking Record Payment opens the settlement modal with two distinct ways to clear the invoice's balance:

10.8 The Invoicing & Delivery Customization Studio (invoice/settings)

Navigate to Sales & Receivables → Invoices → Studio (`invoice/settings`) to tailor every rule of your billing and logistics engine across 5 dedicated configuration tabs.