---
title: "Customers & Accounts Module Documentation"
description: "Documentation for Customers"
---

## Table of Contents
1. [Module Overview (Technical)](#1-module-overview-technical)
2. [Module Overview (Commercial & Business Value)](#2-module-overview-commercial--business-value)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Form Structure](#4-visual-interface--form-structure)
5. [Architectural Flow & Multi-Tenant Convergence](#5-architectural-flow--multi-tenant-convergence)
6. [Common Scenarios & Operational Playbooks](#6-common-scenarios--operational-playbooks)
7. [Troubleshooting & Diagnostic Commands](#7-troubleshooting--diagnostic-commands)
8. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration)
9. [Glossary](#9-glossary)

---

## 1. Module Overview (Technical)

The **Customers & Accounts** module (`public.customers`) constitutes the foundational multi-tenant identity and ledger registry within **Ring2All Billing**. It unifies commercial contract profiles, prepaid credit wallets (`public.wallets`), postpaid credit terms, automated tax jurisdictions, and bidirectional synchronization across voice core infrastructure—specifically **Ring2All PBX** (`ring2all_tenant_id`) and **Ring2All SBC** (`sbc_customer_id`).

### Data Model & System Linkage

```
 ┌────────────────────────────────────────────────────────────────────────┐
 │                      Customer Entity (public.customers)                │
 │  • id: bigint (Canonical Invariant Numeric ID)                         │
 │  • uuid: uuid (Public API Identifier)                                  │
 │  • account_number: VARCHAR(50) (e.g. "ACC-10005")                      │
 │  • company_name: VARCHAR(100) (e.g. "Acme Telecom Corp")               │
 │  • billing_type: 'prepaid' | 'postpaid'                                │
 │  • balance: NUMERIC(14,4) | credit_limit: NUMERIC(14,4)                │
 │  • ring2all_tenant_id: bigint (Linkage to Ring2All Class 5 Tenant)     │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
           ┌─────────────────────────┴─────────────────────────┐
           │                                                   │
           ▼ (1 Customer = 1 PBX Tenant)                       ▼ (1 Customer = N SIP Trunks)
 ┌───────────────────────────────────┐               ┌───────────────────────────────────┐
 │     Ring2All PBX (Class 5 Core)   │               │     Ring2All SBC (Class 4 Core)   │
 │  • Tenant ID: 12                  │               │  • SIP Trunk: "Acme-HQ-GW"        │
 │  • Domains: voice.acme.com        │               │  • Dispatcher Set: ID 102         │
 │  • Extension Quota Enforcement    │               │  • Anti-Fraud Balance Cutoff      │
 └───────────────────────────────────┘               └───────────────────────────────────┘
```

### PostgreSQL Schema Architecture (`public.customers`)
* **Primary Key:** `id` (bigserial) ensures strict immutability. Slugs, corporate names, and alphanumeric codes are strictly prohibited as primary relational foreign keys.
* **Wallet Linkage:** Every customer is atomically assigned an encrypted monetary ledger (`public.wallets`) supporting sub-cent precision (`NUMERIC(14,4)`) for real-time rating and balance sweeps.
* **Auto-Provisioning Flags:** Configurable flags allow automated instant provisioning of Ring2All PBX domains and Ring2All SBC SIP accounts upon account creation.

---

## 2. Module Overview (Commercial & Business Value)

* **Converged Financial Control:** Eliminates silos between Class 4 wholesale VoIP transit billing and Class 5 hosted cloud PBX subscription billing by centralizing all recurring and metered receivables into a single customer ledger.
* **Credit Exposure & Default Risk Elimination:** Real-time OCS (Online Charging System) balance monitoring prevents carrier debt by instantly intercepting live calls and dropping dialogs when prepaid balances reach zero or postpaid credit limits are breached.
* **Automated Dunning & Lifecycle Transitions:** Automated state machine sweeps manage transitions from `active` → `past_due` → `suspended` → `closed`, triggering automated webhook and email notifications.

---

## 3. 🎯 User Roles & Key Capabilities

| User Role | Key Permissions | Core Responsibilities & Workflows |
| :--- | :--- | :--- |
| **Super Administrator** | Full Control (`CRUD`, Billing Overrides) | Defines global billing parameters, approves multi-thousand dollar credit limits, manually overrides customer wallet balances, and executes debt write-offs. |
| **Billing Analyst / NOC** | Read, Edit, Payment Management | Enrolls new corporate accounts, reviews billing ledger statements, verifies automated credit card transactions, and handles dunning investigations. |
| **Telecom Engineer** | Read & Provisioning Mapping | Verifies that customer accounts are correctly synced with Ring2All PBX tenants and Ring2All SBC dispatchers and IP authorization endpoints. |
| **Client Portal Customer** | Self-Service Read & Payments | Views real-time wallet balance, downloads PDF invoices, pays bills via Stripe, and inspects rated CDR summaries. |

---

## 4. Visual Interface & Form Structure

### 4.1 Customers Management (List View)

The **Customers Management** view provides a high-density, real-time DataGrid displaying all corporate accounts with instant search, status filtering, and action menus.

![Customers Management List](/screenshots/billing/customer-accounts/customers/customers-list.png)

### 4.2 Customer Configuration Form (Form View)

The **Customer Configuration** form manages granular account properties across multi-tabbed sections: General Details, Billing & Invoicing, IP Authentication Endpoints, and Assigned Rate Cards.

![Customer Configuration Form](/screenshots/billing/customer-accounts/customers/customers-form.png)

### 4.3 Form Parameter Reference

| Parameter Name | Data Type | Required | Default Value | Description & Business Rules |
| :--- | :--- | :---: | :--- | :--- |
| **Company / Account Name** | `String` | Yes | — | Official legal corporate entity name used on all tax invoices and contractual billing summaries. |
| **Account Number** | `String` | Yes | Auto-generated | Canonical account code (e.g. `ACC-10005`). Used for bank transfers, invoice referencing, and ERP reconciliation. |
| **Billing Mode** | `Enum` | Yes | `prepaid` | `prepaid` (requires positive wallet balance prior to call completion) or `postpaid` (invoiced periodically on net-terms). |
| **Credit Limit** | `Numeric` | No | `0.00` | Maximum allowable negative balance for postpaid customers before outbound traffic is automatically halted. |
| **Billing Currency** | `String` | Yes | `USD` | ISO-4217 3-letter currency code (`USD`, `EUR`, `CAD`, `GBP`) governing all ledger debits and rate card matching. |
| **Payment Terms** | `Enum` | Yes | `due_on_receipt` | Invoicing schedule: `due_on_receipt`, `net_15`, `net_30`, `net_60`. Dictates overdue interest and suspension triggers. |
| **Primary Contact Email** | `Email` | Yes | — | Destination for automated PDF invoice dispatches, payment failure receipts, and balance threshold warnings. |
| **Tax ID / VAT Number** | `String` | No | — | Corporate tax identifier for fiscal compliance and automated tax exemption checks. |
| **Ring2All PBX Tenant ID** | `Integer` | No | — | Invariant numeric ID of the corresponding Class 5 tenant in Ring2All PBX for unified billing sync. |
| **Account Status** | `Enum` | Yes | `active` | Account lifecycle state: `active` (normal service), `suspended` (calls blocked), `fraud_hold` (security lockout), `closed`. |

---

## 5. Architectural Flow & Multi-Tenant Convergence

```
   Incoming Call / Rating Event
                 │
                 ▼
 ┌─────────────────────────────────┐
 │   Ring2All SBC / PBX OCS Check  │
 └───────────────┬─────────────────┘
                 │ Queries Customer Balance
                 ▼
 ┌─────────────────────────────────┐
 │     public.customers Entity     │
 ├─────────────────────────────────┤
 │ Mode: prepaid                   │
 │ Wallet Balance: $49.95          │
 │ Status: active                  │
 └───────────────┬─────────────────┘
                 │
        ┌────────┴────────┐
        ▼                 ▼
 Balance > $0.00    Balance <= $0.00
        │                 │
        ▼                 ▼
 Call Authorized    Call Dropped with SIP 402
 (Real-time debit)  "Payment Required"
```

---

## 6. Common Scenarios & Operational Playbooks

### Scenario A: Enrolling an Enterprise Postpaid Account
1. Navigate to **Customer Accounts** → **Customers** and click **+ Add**.
2. Enter the legal company name and primary billing email.
3. Set **Billing Mode** to `Postpaid`, configure **Credit Limit** to `$500.00`, and select **Payment Terms** as `net_30`.
4. In the **Associated Rate Card** dropdown, select the enterprise retail rate card (e.g. `Standard Retail Rate Card`).
5. Click **Save Customer**. The platform automatically generates the invariant numeric ID and dispatches welcome instructions.

### Scenario B: Emergency Account Suspension (Fraud or Non-Payment)
1. In the customer list, locate the offending account and open the editor.
2. In **Account Status**, toggle from `Active` to `Suspended` or `Fraud Hold`.
3. Save changes. The backend immediately dispatches an RPC signal to Ring2All SBC and Ring2All PBX to drop all active calls and reject subsequent SIP `INVITE` attempts.

---

## 7. Troubleshooting & Diagnostic Commands

### Verifying Customer Balance & Invariant Linkage (PostgreSQL)
```bash
su - postgres -c "psql -d ss_billing -c \"
SELECT c.id, c.account_number, c.company_name, c.billing_type, c.status,
       w.balance, c.credit_limit, c.ring2all_tenant_id
FROM customers c
LEFT JOIN wallets w ON w.customer_id = c.id
WHERE c.id = 1;\""
```

### Checking Active Customer State via REST API
```bash
curl -s -k -X GET "https://192.168.10.29/api/v1/customers/1" \
  -H "Authorization: Bearer <TOKEN>" | jq .
```

---

## 8. Model Context Protocol (MCP) AI Integration

The **Customers & Accounts** module natively connects to the **Ring2All BSS MCP Server**. Autonomous agents, billing operations copilots, and credit analysts interact with customer ledgers, inspect balances, and execute policy adjustments through structured conversational tools.

### Available MCP Tools

| Tool Name | Access Role | Description & Primary Function | Example Arguments |
| :--- | :--- | :--- | :--- |
| `list_billing_customers` | `Billing Operations` / `Admin` | Lists carrier customers, balances, credit limits, and account statuses. | `{"limit": 10, "status": "active"}` |
| `get_billing_customer` | `Billing Operations` / `Admin` | Retrieves full financial profile including wallet balance, DIDs, and subscriptions. | `{"customerId": "1"}` |
| `adjust_customer_balance` | `Super Administrator` | Credits or debits customer wallet with immutable audit ledger recording. | `{"customerId": "1", "amount": 50.00, "description": "Manual top-up"}` |
| `update_customer_status` | `Super Administrator` | Modifies operational status (`active`, `suspended`, `fraud_hold`). | `{"customerId": "1", "status": "suspended", "reason": "Non-payment"}` |
| `get_customer_wallet_ledger` | `Billing Operations` / `Admin` | Queries recent ledger entries (top-ups, call debits, recurring charges). | `{"customerId": "1", "limit": 10}` |

### Sample MCP Tool Execution: `get_billing_customer`

#### Request Payload
```json
{
  "name": "get_billing_customer",
  "arguments": {
    "customerId": "1"
  }
}
```

#### Response Payload
```json
{
  "id": "1",
  "name": "Rodrigo Cuadra",
  "company": "Cuadra Telecom Corp",
  "accountNumber": "ACC-10042",
  "billingType": "prepaid",
  "status": "active",
  "balance": "$248.50",
  "creditLimit": "$0.00",
  "currency": "USD",
  "assignedDidsCount": 4,
  "activeSubscriptionsCount": 2
}
```

### Conversational AI Prompts for Copilot
* *"List all customers with negative balances or suspended accounts."*
* *"What is the current wallet balance and assigned DIDs count for customer ACC-10042?"*
* *"Suspend customer 1 due to suspected IRSF fraud velocity alert."*
* *"Show the last 5 ledger transactions recorded for customer 1."*

---

## 9. Glossary

* **BSS (Business Support System):** Software handling customer accounts, invoicing, payments, subscriptions, and financial ledgers.
* **OCS (Online Charging System):** Real-time rating engine capable of interrogating wallet balances before and during telephone calls.
* **Canonical Numeric ID:** Immutable database integer key (`id`) used for all relational constraints and inter-service communications.
* **Dunning:** Automated process of tracking delinquent accounts, issuing payment reminders, and triggering service suspensions.
* **Model Context Protocol (MCP):** Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.