Skip to content

Standalone ARM — Billing Configurator Specification

1. Overview

The billing configurator is the central tool for setting up billing cycles. It replaces the current NetSuite Suitelet-based configurator (assessed at ~10% functional by Jerry) with a robust, multi-layer implementation.

Current Problems (from Jerry's assessment)

Problem Description
Version divergence 3-4 different versions across clients with no unified codebase
~10% functional Most tabs are partially built; many operations require manual workarounds
No version control Changes made ad-hoc in NetSuite script editor without proper tracking
Tight coupling All logic embedded in NetSuite SuiteScript — cannot be tested or reused
No configuration layer What should be configurable requires code changes
No exception handling No way to add per-student overrides without modifying data directly

Design Goals

  1. Unified configurator — one codebase serving all clients
  2. 3-layer architecture — Generic (shared) → Configurable (point-and-click) → Custom (exceptions)
  3. Web-based UI — modern browser-based interface, independent of NetSuite
  4. Version controlled — all configuration changes tracked and auditable
  5. Template-driven — common billing patterns saved as templates
  6. Wizard + Advanced modes — simple wizard for standard cases, full control for complex ones

2. Three-Layer Architecture Applied to Configurator

Layer 1: Generic Base (~15 Core Features)

These features work identically for every client, out of the box:

# Feature Description
1 Create billing cycle Set period name, start/end dates, frequency
2 Year level management Define year levels for the institution
3 Item catalog browse View all items (fees/discounts) from the item master
4 Student roster view View students grouped by year level, campus, type
5 Family/debtor list View all debtors with student assignments
6 Assign items to year levels Map fees to year levels (bulk)
7 Auto-match students Automatically assign billing instructions to students based on year level
8 Calculate totals Sum charges and discounts per debtor
9 Review assignments Preview billing before generation
10 Generate transactions Create invoices or billing orders
11 Email distribution Send generated transactions to debtors
12 View billing history Access past billing cycles
13 Audit trail Track all configurator changes
14 Import data Import students/debtors from file (CSV/Excel)
15 Export data Export billing data to file

Layer 2: Configurable (Point-and-Click)

Client-specific behavior configured through the UI — no code changes:

Setting Options Example
Billing frequency Annual, Semi-Annual, Term (2/3/4), Monthly, Custom Al Faisal: 4 terms; Pymble: Annual
Payment date mode Flexible (parent chooses) vs Fixed (institution sets) SE: Flexible; AF: Fixed
Payment methods Enable/disable per method Pymble: all 5; SE: 2
Annual discount Enable/disable, percentage Pymble: 2.5%
Sibling discount Enable/disable, rules [PLACEHOLDER: rules per client]
Building levy Enable/disable, opt-in/opt-out Pymble: Opt-in
Mid-year pro-ration Enable/disable, calculation method Pymble: divisible value
Item segmentation Define segment groups By billing engine type
Student type filters Enable/disable student type categorization All, Staff Child, Boarding, etc.
Opening balance handling Include/exclude in payment plan Pymble: Included
Transaction type Invoice or Billing Order Pymble: Billing Order; SE: Invoice
Auto-close paid orders Enable/disable "Paid from Portal" Pymble: Enabled

Layer 3: Custom / Exception

Per-debtor or per-student overrides that don't fit the standard rules:

Exception Type Description Example
Amount override Change the amount for a specific student/debtor Student on partial scholarship
Item exclusion Exclude a specific item for a student/debtor Student exempt from building levy
Item addition Add a one-off item for a student/debtor Late enrollment fee
Payment plan override Custom payment schedule for a debtor Extended payment plan for hardship
Billing hold Hold billing for a debtor pending resolution Dispute in progress
Custom calculation Complex custom logic via plugin [PLACEHOLDER: future examples]

3. Tab-by-Tab Specification

Based on Jerry's 9-tab design, reimagined for the standalone platform.

Tab 1: Billing Cycle Setup

Purpose: Define or select the billing cycle being configured.

Field Type Required Description
Billing Cycle Dropdown / Create New Yes Select existing or create new
Cycle Name Text Yes e.g., "2026 Annual"
Period Start Date Yes Billing period start
Period End Date Yes Billing period end
Frequency Dropdown Yes Annual / Semi-Annual / Term / Monthly / Custom
Number of Terms Integer Conditional Required if frequency = Term
Status Display Auto setup → configuring → review → approved → generating → active

Actions:

  • Create new billing cycle
  • Clone from previous cycle (copy all settings)
  • Unlock a previously approved cycle (with audit log)

Tab 2: Item Segmentation

Purpose: Define billing engine types and group items.

This tab implements the "segmentation" concept — items are grouped into billing engine types for organized processing.

Field Type Description
Segment Name Text e.g., "Tuition", "Levy", "Discount - Sibling", "Discount - Staff"
Items in Segment Multi-select Select items from the item catalog
Processing Order Integer Order in which segments are processed
Apply Rule Dropdown Charge / Discount

Pre-configured segments (auto-created for new tenants):

  1. Tuition Fees
  2. Levies & Compulsory Charges
  3. Optional Charges
  4. Sibling Discounts
  5. Staff Discounts
  6. Scholarships / Bursaries
  7. Other Discounts

Tab 3: Item Selection

Purpose: Select which items are included in this billing cycle.

Column Description
Item Code From item catalog
Item Name Display name
Category Charge / Discount
Segment Billing engine type
Default Amount Default price from item master
Include Checkbox — include in this cycle

Features:

  • Filter by segment, category, status
  • Bulk select/deselect
  • Search by item name or code
  • View item pricing rules (year level variations)

Tab 4: Family Selection

Purpose: Select which families (debtors) are included in this billing cycle.

Column Description
Debtor Code Family identifier
Billing Title Family display name
Students Number of enrolled students
Year Levels List of year levels
Campus Campus affiliation
Status Active / Inactive / On Hold
Include Checkbox

Features:

  • Filter by year level, campus, status, student type
  • Bulk select/deselect (e.g., "Select all active families")
  • View family detail (expand to see students)
  • Exclude specific families (with reason)

Tab 5: Items-to-Years Mapping

Purpose: Map selected items to year levels. This is the core billing instruction creation step.

Year Level → Item 1 Item 2 Item 3 ...
Pre-K $X — $X
K $X $X $X
Year 1 $X $X $X
Year 7 $Y $X $Y
Year 12 $Z $X —

Features:

  • Matrix view (year levels as rows, items as columns)
  • Amounts editable per cell (override default)
  • Bulk set amount for entire column (apply same price to all years)
  • Bulk set amount for entire row (apply all items to a year at the same price)
  • Color coding: green = set, yellow = overridden, grey = excluded
  • Import amounts from spreadsheet (paste from Excel)

Tab 6: Exceptions

Purpose: Add per-student or per-family exceptions.

Field Type Description
Student / Family Search Find the student or debtor
Item Dropdown Which item to override
Exception Type Dropdown Amount override / Exclude / Add / Hold
New Amount Currency For amount overrides
Reason Text Required explanation
Approved By Display Auto-populated from logged-in user

Features:

  • View all existing exceptions
  • Bulk exception import (CSV with columns: debtor_code, item_code, exception_type, amount, reason)
  • Exception audit trail
  • Reusable exception templates (e.g., "Scholarship 50%")

Tab 7: Schedule & Payment Configuration

Purpose: Configure payment methods and schedules for this billing cycle.

Setting Type Description
Payment Methods
Credit Card (eway) Toggle Enable/disable
Direct Debit (ABA) Toggle Enable/disable
B Pay Toggle Enable/disable
Edstart Toggle Enable/disable
Other Toggle Enable/disable
Payment Frequencies
Weekly Toggle + Max Installments
Fortnightly Toggle + Max Installments
Monthly Toggle + Max Installments
Term-based Toggle
Annual (Full) Toggle + Discount % e.g., 2.5% discount
Date Configuration
Date Mode Radio Flexible / Fixed
Fixed Dates Date list If Fixed: define payment dates
First Payment Date (Flexible) Date Earliest selectable date
Last Payment Date (Flexible) Date Latest selectable date
Opening Balance
Include Opening Balance Toggle Include prior balance in payment plan
Opening Balance Source Dropdown ERP / Manual / Calculated

Tab 8: Review & Approval

Purpose: Preview the complete billing run before generation.

Section Content
Summary Total debtors, total students, total charges, total discounts, net amount
Breakdown by segment Per segment: item count, total amount
Breakdown by year level Per year: student count, total charges
Exceptions list All exceptions applied
Comparison to prior cycle Delta analysis: new families, removed families, amount changes
Validation warnings Missing items, unassigned students, families without items

Actions:

  • Approve (sets status → approved)
  • Reject (returns to configuration with comments)
  • Export review report (PDF / Excel)

Tab 9: Generation & Distribution

Purpose: Generate transactions and distribute to parents.

Step Description
Generate Transactions Create invoice or billing order records
Generate PDFs Create PDF documents for each transaction
Generate Payment Links Create unique portal links per transaction
Email Distribution Send invoice emails with PDF + payment link
Export for ERP Push generated transactions to connected ERP
Monitor Delivery View email delivery status per debtor

Generation Options:

Option Description
Batch size Number of records to generate per batch
Dry run Generate preview without creating records
Selective generation Generate for specific debtors only
Regenerate Regenerate for specific debtors (voiding previous)

4. Wizard Mode (Simplified Flow)

For standard billing cycles, a wizard guides the user through the minimum required steps:

Step 1: Select or create billing cycle
    │
Step 2: Confirm items (pre-loaded from template or prior cycle)
    │
Step 3: Confirm families (auto-selected: all active debtors)
    │
Step 4: Review amounts (items-to-years matrix)
    │
Step 5: Add exceptions (if any)
    │
Step 6: Review summary
    │
Step 7: Approve & Generate

The wizard is the default experience for the Saint Edwards pattern (automated, minimal configuration).

5. Template System

5.1 Billing Templates

Save a complete billing cycle configuration as a template:

Template Field Description
Template Name e.g., "Annual Billing - Standard"
Items Pre-selected items
Segments Pre-configured segments
Items-to-Years Mapping Pre-set amounts
Payment Configuration Pre-set payment methods and frequencies
Exception Templates Pre-defined exception rules

5.2 Exception Templates

Save common per-student overrides:

Template Description Example
Scholarship 50% Reduce all charges by 50% Applied to scholarship students
Scholarship 100% Exclude all charges Full scholarship
Staff Child Discount Apply staff discount item Staff children
Building Levy Exempt Exclude building levy Specific exemption
Sibling Discount 2nd Child Apply 2nd child discount 2nd child in family
Sibling Discount 3rd+ Child Apply 3rd+ child discount 3rd or more child

6. Version History & Audit

6.1 Configurator Change Tracking

Every change in the configurator is logged:

Field Description
Timestamp When the change was made
User Who made the change
Tab Which configurator tab
Action What was changed (add, remove, update)
Entity Which item, debtor, or student was affected
Old Value Previous value
New Value New value
Reason User-provided reason (required for exceptions)

6.2 Cycle Snapshots

At each status transition, a full snapshot of the billing cycle configuration is saved:

  • setup → configuring — initial snapshot
  • configuring → review — pre-review snapshot
  • review → approved — approved snapshot (immutable)
  • approved → generating — generation snapshot

This ensures:

  • Complete audit trail of what was approved
  • Ability to compare any two snapshots
  • Rollback to a previous snapshot if needed

7. Configurator Permissions

Permission Description Roles
billing.cycle.create Create new billing cycles Admin, Billing Manager
billing.cycle.configure Modify billing configuration Admin, Billing Manager
billing.cycle.approve Approve billing cycle for generation Admin, Finance Manager
billing.cycle.generate Execute transaction generation Admin, Billing Manager
billing.exception.create Add exceptions Admin, Billing Manager
billing.exception.approve Approve exceptions above threshold Admin, Finance Manager
billing.template.manage Create/edit templates Admin
billing.audit.view View audit trail Admin, Auditor

Separation of duties: The person who configures should not be the same person who approves (configurable enforcement).

8. Mid-Year Enrollment Handling

8.1 Pro-Ration Calculation

When a student enrolls mid-year:

Pro-rated amount = Annual amount × (remaining_periods / total_periods)

Where:

  • total_periods = determined by the billing cycle's midyear_divisible_value (e.g., 12 for monthly, 4 for terms)
  • remaining_periods = periods from enrollment date to cycle end

8.2 Mid-Year Workflow

New student enrolled mid-year
    │
    ▼
Admin opens active billing cycle
    │
    ▼
"Add Mid-Year Student" action:
    ├── Select student
    ├── Set enrollment date
    ├── System auto-calculates pro-rated amounts
    ├── Admin reviews and approves pro-rated amounts
    │
    ▼
System generates billing instructions for the student
    │
    ▼
System generates transaction (invoice/billing order) for the student
    │
    ▼
System sends billing communication to parent
    │
    ▼
Parent sets up payment plan via portal

8.3 Mid-Year Withdrawal

When a student withdraws mid-year:

Student marked as withdrawn
    │
    ▼
System calculates refund/credit based on pro-ration
    │
    ▼
Admin reviews and approves credit note amount
    │
    ▼
System generates credit note
    │
    ▼
System cancels remaining RPS records
    │
    ▼
System processes refund (where applicable)

9. Appendix: Configurator Feature Comparison

Feature Current NetSuite (% done) Standalone ARM (target)
Billing cycle creation 80% 100%
Item segmentation 30% 100%
Item selection 70% 100%
Family selection 50% 100%
Items-to-years mapping 60% 100%
Exception handling 10% 100%
Payment configuration 40% 100%
Review/approval 20% 100%
Transaction generation 70% 100%
Email distribution 50% 100%
Mid-year handling 20% 100%
Template system 0% 100%
Wizard mode 0% (Saint Edwards only) 100%
Version history 0% 100%
Audit trail 0% 100%
Permissions 0% 100%
Overall ~10% (Jerry's estimate) 100%