RecurringInvoice/index • RecurringInvoice/add • RecurringInvoice/inspect • RecurringInvoice/settings Recurring Billing, Stock Replenishment Contracts, 360° Dossier & Studio
Master automated subscription billing, scheduled physical inventory replenishment contracts, Monthly Recurring Revenue (MRR/ARR) forecasting, warehouse stock-readiness radar, annual CPI price escalations, and the 360° Contract Dossier.
11.1 Plain-English Concept: Service Retainers vs. Physical Stock Replenishment Contracts
In traditional accounting software, "recurring invoices" only handle intangible monthly fees like web hosting or bookkeeping retainers. However, in wholesale, distribution, medical supplies, hygiene, and equipment servicing, recurring contracts frequently include physical consumables that must be shipped from a warehouse every cycle (e.g., 50 boxes of printer paper or 20 drums of industrial sanitizer every month).
Keystone X bridges Subscription Billing and Warehouse Inventory Control into a single unified engine:
1. Normalized MRR & ARR
Whether a client pays Weekly, Monthly, Quarterly, Bi-Annually, or Yearly, Keystone X mathematically normalizes every active contract into a single comparable Monthly Recurring Revenue (MRR) and Annualized Run Rate (ARR = MRR × 12) metric.
2. Stock Readiness Radar
Before a scheduled billing cycle runs, Keystone X inspects your Fulfillment Warehouse Hub to verify whether sufficient physical stock is on hand for every SKU on the contract, classifying each contract as Stock Ready, Low Buffer, or Stock Shortfall.
3. Annual CPI Escalation
Multi-year SLA and supply contracts often include an annual inflation clause (e.g., +6.5% per annum). Keystone X projects and applies your configured Annual CPI Escalation % automatically on contract anniversaries.
11.2 The Recurring Billing & Replenishment Command Center (RecurringInvoice/index)
Navigate to Sales & Receivables → Recurring Invoices (`RecurringInvoice/index`) to open the command center.
📸 [SCREENSHOT PLACEHOLDER: recurring-billing-command-center.png]
How to Capture: Open /RecurringInvoice/index. Capture the 6 KPI cards at the top, the 12-Month Recurring Revenue & Inventory Replenishment Forecast chart on the left, and the Contract SKU Stock Radar on the right.
The 6 Executive Telemetry Cards
| KPI Card | What It Measures & Sub-Indicators |
|---|---|
| 1. Normalized MRR | Monthly Recurring Revenue across all active contracts, plus the annualized run-rate (ARR: R X,XXX) underneath. |
| 2. Active Contracts | Count of currently active recurring profiles, plus the weighted Avg Gross Margin % (based on selling price vs. warehouse unit cost) and count of paused contracts. |
| 3. Stock Readiness | Shows how many physical replenishment contracts are Ready (green) alongside badges for Low Buffer (amber: stock covers 1 cycle but less than 2 cycles) and Shortfall (red: current warehouse stock cannot fulfill the next run). |
| 4. Next 30d Billing | Projected gross billing scheduled to trigger within the next 30 days, plus the associated Stock Cost required to fulfill those shipments. |
| 5. 7-Day Run Queue | Count of contracts due to execute within the next 7 days, plus your configured Reserve Lead window (e.g., Reserve Lead: 3d). |
| 6. Lifetime Billed | Total cumulative revenue generated by all recurring contracts to date, plus the total count of Tax Invoices (`INV-`) automatically spawned. |
11.3 Forecasting Chart, Contract SKU Stock Radar & Master Register
1. 12-Month Recurring Revenue & Inventory Replenishment Forecast
The left-hand visual chart projects your contract cash flows 12 months into the future, splitting each month into two side-by-side bars:
- Projected Contract Revenue (Blue Bar): Expected top-line billing for that month across all Weekly, Monthly, Quarterly, Bi-Annual, and Annual schedules (including scheduled CPI escalations).
- Stock Replenishment COGS (Green Bar): The physical inventory cost required to fulfill those scheduled deliveries in that specific month.
2. Contract SKU Stock Radar (Right Panel)
Aggregates every physical inventory SKU tied to active recurring contracts and ranks them by stockout urgency:
- SKU / Item: Product name, SKU code, and how many active contracts depend on it.
- Req / Stock: Total units required per billing cycle vs. actual physical units currently on hand.
- Cycles Covered: Calculates `Stock On Hand / Cycle Demand` (e.g., `0.5x cycles` in red if you don't even have enough for the next run, `1.5x cycles` in amber, or `4.2x cycles` in green).
3. Multi-Filter Bar & Contract Master Register
Below the charts, you can filter the register instantly by Client / Contract / SKU Search, Lifecycle Status (`Active`, `Paused`, `At-Risk / Shortfall`), Contract Type (`Stock Replenishment`, `SLA Retainer`, `Subscription`, `Equipment Lease`), and Cadence (`Daily`, `Weekly`, `Monthly`, `Quarterly`, `Bi-Annually`, `Annually`), or click Export CSV.
| Register Column | Details & Row Actions |
|---|---|
| Contract & Client | Contract Code badge (e.g., SUB-0012), Contract Title, clickable link to the Client Profile, and Contract Classification pill. |
| Cadence & Schedule | Displays the frequency pill (e.g., MONTHLY), human-readable schedule rule (e.g., Day 25 of month), and a +6.0% Annual CPI badge if inflation escalation is active. |
| Next Run & Lead | Next scheduled generation date and countdown badge (Due Today / Ready, In 4 days, or Scheduled). |
| Stock Readiness | Shows Stock Ready (green), Low Buffer (amber), Stock Shortfall (red with exact SKU shortfall count), or Service Only (blue) along with the total physical item count. |
| Cycle Value & MRR | Gross invoice amount per cycle on top, normalized `MRR` value in blue, and `Gross Margin %` badge in green. |
| Runs & Lifetime | Number of cycles executed so far and cumulative lifetime rand value billed. |
| Actions (4 Direct Buttons) |
|
11.4 Building a Recurring Contract (RecurringInvoice/add & edit)
Click + New Recurring Contract to open the Contract Builder (`RecurringInvoice/add`). As you add items and change frequencies, a sticky right-hand Live Contract Telemetry sidebar calculates your Cycle Value, Normalized MRR, Annualized Run Rate (ARR), Gross Margin %, and Warehouse Stock Readiness in real time!
📸 [SCREENSHOT PLACEHOLDER: recurring-contract-builder.png]
How to Capture: Navigate to /RecurringInvoice/add. Fill in a Contract Title, select a Stock Replenishment classification, add a warehouse SKU so the Live Stock Availability badge turns green in the line item table, and capture both the main form and the sticky dark Live Contract Telemetry card on the right.
| Section & Field | Input Name | Purpose & Operational Logic |
|---|---|---|
| Contract Code | contract_code |
Unique contract reference (auto-filled using your Studio prefix, e.g., SUB-0005). |
| Contract / Profile Title | contract_name |
Descriptive commercial name (e.g., Monthly Hygiene Consumables & Dispenser SLA). |
| Contract Classification | contract_type |
Categorizes the agreement into Stock Replenishment, Managed SLA / Retainer, Recurring Subscription, or Equipment Lease / Rental. |
| Fulfillment Warehouse Hub | fulfillment_warehouse_id |
Selects which physical warehouse branch (`warehouses`) supplies the inventory for this contract (or leave on All Warehouses / Consolidated Stock). |
| Annual CPI Escalation (%) | price_escalation_pct |
Sets the annual percentage price increase applied on contract anniversary dates (e.g., 6.00%). |
| 3 Automation Switches | auto_reserve_stockauto_deduct_stockauto_send_email |
|
| Billing Cadence & Dynamic Day Selectors | frequencyday_of_weekday_of_monthmonth_of_year |
Select Daily, Weekly, Monthly, Quarterly, Bi-Annually, or Annually. The form dynamically reveals the exact scheduling inputs required:
|
| First / Next Run Date & Contract Expiry Date | next_run_dateend_date |
Sets the exact date of the next automated run and an optional contract termination date (leave Expiry Date blank for an evergreen rolling contract). |
| Line Items with Live Stock Availability | item_id[], quantity[], unit_price[], tax_rate[] |
As you select an inventory item and type a quantity, the Stock Availability column immediately compares your requested quantity against current warehouse stock and displays a live badge: In Stock (X avail) (green), Tight Buffer (X avail) (amber), Shortfall: Need Y, Have X (red), or Service / Non-Stock (blue), along with the item's unit cost and live gross margin. |
11.5 The 360° Contract & Replenishment Dossier (RecurringInvoice/inspect/{id})
Clicking the Eye icon on any recurring profile opens the 360° Contract & Replenishment Dossier (`RecurringInvoice/inspect/{id}`), providing deep operational visibility into a single contract.
📸 [SCREENSHOT PLACEHOLDER: recurring-contract-360-dossier.png]
How to Capture: Open /RecurringInvoice/inspect/{id} for an active contract. Capture the top header buttons (Clone Contract, Edit Contract, Generate Invoice Now), the 4 KPI cards, the 12-Cycle Forward Billing & Escalation Simulator, and the Generated Tax Invoices Audit Ledger.
- Top Header Actions: Includes Clone Contract (`RecurringInvoice/cloneProfile/{id}` — duplicates the entire contract structure into a new profile in 1 click), Edit Contract, Generate Invoice Now, and Pause / Resume.
- Contract Line Items, Warehouse Stock Coverage & Unit Economics Table: Shows each SKU's Cycle Qty, Warehouse On-Hand Stock, exact Cycles Covered (`4.5x cycles`), Unit Cost, Unit Price, Gross Margin %, and Line Total.
- 12-Cycle Forward Billing & Escalation Simulator: Simulates the next 12 scheduled billing runs (`Cycle #1` to `Cycle #12`), showing exact future run dates, whether an annual CPI Escalation (`+X% CPI Applied`) triggers on that cycle, projected gross amount, and stock reservation status.
- Generated Tax Invoices Audit Ledger: Lists every historical Tax Invoice (`INV-`) spawned by this contract, showing whether it was triggered by the Automated Cron Engine or a Manual Operator Run, along with its current payment status and direct links to view or download the PDF.
11.6 The Recurring Billing & Replenishment Studio (RecurringInvoice/settings)
Click Studio & Rules (`RecurringInvoice/settings`) in the Recurring Invoices header to configure system-wide contract governance across 4 Studio Cards:
| Studio Governance Card | Settings & Enforcement Options |
|---|---|
| 1. Contract Numbering, Classification & Default Hub | Configure the Contract Code Prefix (`contract_prefix`, default `SUB-`), Default Contract Classification (`default_contract_type`), Default Fulfillment Warehouse Hub (`default_warehouse_id`), and Default Generated Invoice Status (`Draft (Review Before Sending)` vs. `Sent / Finalized Immediately`). |
| 2. Warehouse Stock Reservation & Stockout Enforcement |
|
| 3. Annual CPI Escalation, Proration & Contract Governance | Configure the Default Annual CPI Escalation % (`default_escalation_pct`), Mid-Cycle Proration Formula (`proration_method`) (`Actual Calendar Days`, `Standardized 30-Day Bankers Month`, or `No Proration / Full Cycle`), Renewal Reminder Lead Window (`renewal_reminder_days`), and Grace Period Before Auto-Suspend (`grace_period_days`). |
| 4. Customer Email Dispatch & Connected ERP Studios | Toggle Auto-Email Generated Tax Invoices (`auto_send_email_default`) and customize the Recurring Invoice Email Subject Template (`email_subject_template`) using dynamic merge tags (`{company_name}`, `{invoice_number}`, `{contract_code}`). |