Volume 4 • Article #08 Routes:
customer/index, customer/add, customer/edit, customer/profile, customer/settings Accounts Receivable & 360° CRMCustomer Directory, Sage-Style Onboarding, 360° Client Profile & Governance Studio
Master your Accounts Receivable (AR) debtor book: onboard corporate and individual clients, link parent/subsidiary hierarchies, route invoices and statements to specialized department contacts, manage credit limits and unallocated credit wallets, inspect 360° financial & operational history, and impersonate the Client Self-Service Portal.
In This Article
1. Plain-English Accounting: Debtors, Credit Limits & Unallocated Credit Wallets
Every Customer in Keystone X is a sub-ledger account under your General Ledger's Accounts Receivable (Trade Debtors — Asset Account 1100). Understanding three key financial numbers on every customer record will give you complete control over cash flow:
1. Balance Due (AR Owing)
The total unpaid amount across all issued Tax Invoices for this customer. Because Accounts Receivable is an Asset on your Balance Sheet, issuing an invoice increases (Debits) their Balance Due, while recording a payment or Credit Note reduces (Credits) their Balance Due.
2. Unallocated Credit Wallet
When a customer pays a deposit upfront (e.g., against a Pro-Forma Invoice) or overpays an invoice, the extra money isn't lost—it sits safely in their Credit Wallet (`credit_balance`). On your Balance Sheet, this is tracked as a liability/retainer until you apply it to pay off their next Tax Invoice with a single click!
3. Credit Limit & Exposure
The maximum unpaid invoice balance you allow a customer to carry at one time (e.g., R 50,000.00). Setting Credit Limit to 0.00 means Unlimited / No Restriction. When set above zero, Keystone X calculates a live Credit Utilization % Bar on the customer's 360° profile.
2. Customer Directory Command Center (customer/index)
Navigate to Sales & CRM → Customers (customer/index) to view your master debtor directory.
SCREENSHOT PLACEHOLDER
vol4-08-customer-directory-index.pngHow to capture this screenshot:
- Navigate to
customer/index. - Ensure the table shows both Corporate (Company) and Individual customers, ideally including a subsidiary customer with a Sub of: Parent Company badge and at least one customer with a green Credit Wallet pill.
- Capture the full screen showing the top header actions, the 4 KPI cards, the Quick Filter Toolbar, and the DataTables directory.
A. Top Header Action Buttons
| Button | Target Route | Purpose |
|---|---|---|
| Sales Pipeline | lead/index |
Jumps directly to the Pre-Sales Leads & Opportunities Kanban funnel. |
| Contacts Directory | people/index |
Opens the centralized People & Contacts Registry where individual human contacts across all companies are managed. |
| New Customer | customer/add |
Requires `create_customers` permission. Opens the Customer Onboarding workspace. |
| (Gear Icon) | customer/settings |
Requires `manage_settings` permission. Opens the Customer Directory Studio. |
B. The 4 Customer KPI Cards (Customizable up to 6 in Studio)
| KPI Card | Studio Key | What It Measures |
|---|---|---|
| Total Customers | total_customers |
Total count of active corporate and individual accounts in your directory. |
| Corporate Accounts | corporate_accounts |
Count of B2B Company entities (`is_company = 1`). |
| Individual Clients | individual_clients |
Count of B2C Individual / Residential clients (`is_company = 0`). |
| Total Receivables (AR) | total_receivables |
Total unpaid balance owed to your business across all customers (`total_invoiced - total_paid`). |
| Unallocated Credits (Optional in Studio) | unallocated_credits |
Total retainer / overpayment credit balances held across all customer Credit Wallets. |
| Accounts in Arrears (Optional in Studio) | accounts_in_arrears |
Count of customers who currently have an unpaid balance greater than zero. |
C. Quick Filter Pills & Customer Table Columns
Above the table, use the Quick Filter Pills to slice the directory instantly without reloading the page: All, Companies, Individuals, Owes Balance, or Has Credit.
| Column | Studio Key | Details Displayed |
|---|---|---|
| Customer / Account Name | customer_name |
Avatar badge + clickable Account Name (`customer/profile/{id}`). If the account is a subsidiary branch, displays an info pill: Sub of: [Parent Company]. Can also display Tax/VAT No. if enabled in Studio (`show_vat_under_name`). |
| Type | type |
Displays a Company badge (Blue) or Individual badge (Grey). |
| Primary Contact | primary_contact |
Full name of the linked primary person (`people` registry) or fallback contact name. |
| Contact Details | contact_details |
Clickable `mailto:` email address and phone number. |
| City / Region (Optional) | city_region |
Customer's city/town from their billing address. |
| Tax / VAT No. (Optional) | vat_number |
Customer's Tax/VAT registration number in monospace font. |
| Credit Limit (Optional) | credit_limit |
Configured credit limit or Unlimited. |
| Balance Due | balance_due |
Red bold amount if the customer owes money, or green R 0.00 if settled. If the customer has money in their Credit Wallet (`credit_balance > 0`), displays a green pill underneath: Credit: R X,XXX.XX. |
| Actions | Always Visible | View 360° Profile Statement Edit Delete |
3. Sage-Style 5-Tab Customer Onboarding & Editing (customer/add & customer/edit/{id})
Keystone X uses a clean, Sage-inspired Horizontal Tabbed Architecture for customer onboarding and maintenance so your screen is never cluttered with long scrolling forms.
- When Creating a Customer (`customer/add`), you see 4 Tabs: 1. General & Address, 2. Contacts & Document Routing, 3. Financial Terms & Credit, and 4. Automations & Notes.
- When Editing an Existing Customer (`customer/edit/{id}`), a 5th Tab unlocks: 5. Activity Timeline, along with a top summary banner showing live Total Invoiced, Total Paid, and Balance Due badges.
SCREENSHOT PLACEHOLDER
vol4-08-customer-edit-tabs.pngHow to capture this screenshot:
- Open any active corporate customer via
customer/edit/{id}. - Ensure Tab 1: General & Address is active, showing the Financial Summary Banner at the top, the 5 horizontal Sage navigation pills, the Business / Company vs. Individual Person selector cards, and the Address block.
- Capture the full workspace.
Tab 1: General & Address (#pane-general)
| Field / Control | Input Name | Behavior & Purpose |
|---|---|---|
| Customer Entity Type Cards | is_company (1 or 0) |
Interactive selector cards at the top of Tab 1: • Business / Company ( 1): Reveals the Registered Company Name and Parent Company / Head Office fields. • Individual Person ( 0): Hides corporate fields and switches phone label to Landline / Secondary Phone. |
| Registered Company Name | company_name |
Required when Entity Type is Business / Company. |
| Parent Company / Head Office | parent_id |
Optional dropdown of existing corporate customers. Links this customer as a Subsidiary / Branch under a Holding Company or Head Office (visualized on the Parent's 360° Corporate Hierarchy tab). |
| Account Contact First & Last Name | contact_first_name, contact_last_name |
On customer/add, you can toggle between Create New Contact (enters First/Last Name, Email, Mobile) or Link Existing Person (selects from your `people` registry). |
| Billing / Account Email | email |
Primary email address for invoices, quotes, statements, and Client Portal login. |
| Main Office / Switchboard Phone | contact_phone |
Primary landline or switchboard number. |
| Mobile / Cell Number | mobile_phone |
Direct mobile number for SMS/WhatsApp communication. |
| Physical & Billing Address Card | address, address_line2, city, province_state, postal_code, country |
Complete street address, suite/building, city, province/state, postal code, and country printed on all legal Tax Invoices, Quotes, Delivery Notes, and Statements. |
4. Tab 2: People Registry & Financial Document Routing (#pane-contacts)
In larger corporate accounts, the person who approves a Quote (e.g., Procurement Manager) is rarely the same person who pays an Invoice (Accounts Payable) or reconciles the Monthly Statement (Financial Controller). Tab 2 solves this cleanly.
SCREENSHOT PLACEHOLDER
vol4-08-customer-contacts-routing.pngHow to capture this screenshot:
- Inside
customer/edit/{id}, click Tab 2: Contacts & Document Routing. - Capture both the Associated Contacts & People card and the Financial Document Routing card below it.
| Control / Dropdown | Input Name | How It Works |
|---|---|---|
| Primary Contact Person | primary_contact_id |
Selects the main human contact from the People directory (`people/index`) for this customer. |
| Additional Linked Contacts | linked_contacts[] |
Searchable multi-select checkbox dropdown allowing you to attach multiple staff members (buyers, site managers, bookkeepers) to this company. |
| Invoices & Receipts Routing | billing_contact_id |
Directs Tax Invoices and Payment Receipts to a specific linked contact (e.g., Accounts Payable) instead of the Primary Contact. |
| Quotes & Estimates Routing | quote_contact_id |
Directs Commercial Proposals and Quotes to the buyer or procurement contact. |
| Monthly Statements Routing | statement_contact_id |
Directs Monthly Account Statements and overdue reminders to the credit controller or finance contact. |
Tabs 3, 4 & 5 on the Customer Workspace
| Tab | Field / Control | Description & Accounting Impact |
|---|---|---|
Tab 3: Financial Terms & Credit (#pane-financial) |
Default Payment Terms (payment_term_id) |
Assigns a payment term (e.g., Due on Receipt, Net 15, Net 30, 60 Days). Whenever you create a new Tax Invoice for this client, the Due Date is calculated automatically from this setting. |
Preferred Bank Account Override (preferred_bank_account_id) |
Normally, your company's Primary Bank Account is printed on PDFs. If you want this specific customer to pay into a different bank account (e.g., USD Foreign Account or Branch B Account), select it here—all PDFs generated for this customer will automatically print those banking details! | |
Credit Limit (credit_limit) |
Maximum allowed AR balance (set to 0.00 for unlimited credit). |
|
Tax / VAT Registration No. (company_vat_number) |
Customer's SARS/Tax VAT number (e.g., 4012345678), printed on all Tax Invoices and Credit Notes for tax compliance. |
|
Tab 4: Automations & Notes (#pane-automations) |
Auto Email Notifications (email_notifications) |
Toggle switch. When enabled, dispatches instant transactional emails for new invoices, receipts, and credit notes. |
Automated Overdue Reminders (enable_overdue_reminders) |
Toggle switch. When enabled, sends automated payment reminder emails when open invoices pass their due date. | |
Internal CRM Notes (notes) |
Private staff-only notes (special discount agreements, gate codes, delivery instructions). Strictly hidden from the Client Portal. | |
Tab 5: Activity Timeline (#pane-timeline, Edit Mode) |
Quick Activity Log Bar (Call, Meeting, Email, Note) |
Allows staff to log phone calls, site visits, email exchanges, or internal notes with a timestamp and user badge (`customer/addActivity`). |
5. The 360° Customer Profile & 9-Tab Workspace (customer/profile/{id})
Clicking any customer's name in the directory opens their **360° Customer Profile** (`customer/profile/{id}`), bringing together every financial transaction, operational job, asset, and communication into one screen.
SCREENSHOT PLACEHOLDER
vol4-08-customer-360-profile.pngHow to capture this screenshot:
- Navigate to
customer/profile/{id}for an active customer with invoices, quotes, and projects. - Capture the top header bar (showing Statement, Login as Client, Edit Profile), the 4 Financial KPI Cards (including the Credit Limit utilization bar), the left Contact/Details sidebar, and the right-hand 9-tab workspace.
A. 360° Profile KPI Cards
- Total Invoiced: Lifetime value of all Tax Invoices billed to this customer.
- Total Paid: Lifetime value of all payments received from this customer.
- Balance Due (AR): Current outstanding balance (highlighted in red if owing, green if settled).
- Unallocated Credit Wallet / Credit Limit Progress Bar: Displays available retainer/overpayment credit in green, plus a live visual progress bar showing percentage of Credit Limit utilized (turns Amber above 75% and Red above 90%).
B. The 9-Tab Operational & Financial Ledger
| 360° Profile Tab | Tab Target ID | What You Can View & Do Inside This Tab |
|---|---|---|
| 1. Activity & Notes | #timeline |
Quick-log a Note, Call, Email, or Meeting right from the profile and review the chronological interaction history. |
| 2. Invoices | #invoices |
Lists all Tax Invoices for this client with Issue Date, Due Date, Total, Balance Due, Status badge, and a + New Invoice button pre-linked to this customer. |
| 3. Quotes | #quotes |
Lists all Commercial Quotes & Pro-Forma Invoices for this client with a + New Quote shortcut. |
| 4. Credit Notes | #credits |
Lists all Credit Notes (`CN-`) issued to this client with a + Issue Credit Note button. |
| 5. Projects | #projects |
Lists all ERP Projects linked to this client with start/deadline dates, status, and a + New Project shortcut. |
| 6. Job Cards | #jobs |
Lists all Field Service Job Cards (`JC-`) with priority, status, scheduled date, and a + New Job Card button. |
| 7. Support Tickets | #tickets |
Lists all Helpdesk Support Tickets submitted by or logged for this client, with SLA priority and status badges. |
| 8. Assets / Fleet | #vehicles |
Lists all Customer Equipment, Vehicles, or Serialized Assets registered to this client (`vehicle/view/{id}`) with a + Add Asset / Vehicle button. |
| 9. Corporate Hierarchy (Conditional) | #hierarchy |
Appears automatically if this customer has a Parent Company or Subsidiary Branches. Displays the Parent / Head Office card and a full table of Subsidiary & Branch Accounts with their individual balances due. |
6. One-Click Client Portal Impersonation (customer/impersonate/{id})
At the top right of the 360° Customer Profile (`customer/profile/{id}`), authorized staff will see the Login as Client button.
How Portal Impersonation Works: Clicking Login as Client (`customer/impersonate/{id}`) opens a new browser tab logged directly into the Client Self-Service Portal (`portal/dashboard`) as that specific customer—without needing their password! You can see the exact invoices, quotes awaiting signature, projects, and statements the customer sees, and click Exit Impersonation in the portal banner to return to your ERP workspace.
7. Customer Directory Governance Studio (customer/settings)
Click the Gear Icon () on `customer/index` to open the **Customer Directory Studio** (`customer/settings`). It features a live interactive preview and 5 Customization Tabs:
SCREENSHOT PLACEHOLDER
vol4-08-customer-studio.pngHow to capture this screenshot:
- Navigate to
customer/settings. - Capture the Studio interface showing the 5 left/top navigation tabs (KPI Cards, Table Columns, Filters & Sorting, Onboarding Defaults, Form Field Governance) and the Live Interactive Directory Preview below.
| Studio Tab | Configurable Controls | Impact on Customer Directory & Forms |
|---|---|---|
| 1. KPI Cards | Toggle & reorder up to 6 KPI cards: total_customers, corporate_accounts, individual_clients, total_receivables, unallocated_credits, accounts_in_arrears |
Controls which summary metric cards appear at the top of `customer/index` and in what order. |
| 2. Table Columns | Toggle 8 columns + 2 display options: show_subsidiary_badge, show_vat_under_name |
Customizes the columns shown in the Customer Directory DataTable and whether subsidiary badges or VAT numbers appear beneath the customer's name. |
| 3. Filters & Sorting | show_quick_filters, default_sort_column, default_sort_dir, default_page_length (10/25/50/100) |
Controls the Quick Filter toolbar visibility, default sorting column/direction, and rows per page. |
| 4. Onboarding Defaults | default_entity_type (Company vs. Individual), default_country, default_credit_limit, default_email_notifications, default_overdue_reminders |
Pre-populates default values whenever staff open `customer/add` to onboard a new client. |
| 5. Form Field Governance | 4 Mandatory Validation Rules: require_email, require_phone, require_vat_for_company, require_billing_address |
Enforces strict data governance (e.g., preventing staff from saving a corporate customer without entering their SARS/Tax VAT Registration Number or Billing Address). |