Plans & Packages Catalog Module Documentation

Module Overview (Technical)
Module Overview (Commercial & Business Value)
🎯 User Roles & Key Capabilities
Visual Interface & Form Structure
Architectural Flow & Subscription Provisioning
Common Scenarios & Operational Playbooks
Troubleshooting & Diagnostic Commands
Model Context Protocol (MCP) AI Integration
Glossary

1. Module Overview (Technical)

The Plans & Packages Catalog module (public.plans) defines the commercial products and subscription templates offered by the telecom operator. It encapsulates monthly base prices, bundled resource allowances (concurrent channels, extension seats, pooled outbound minutes, call recording storage GB), Fair Usage Policies (FUP), and overage pricing models.

Service Types Supported

Hosted Cloud PBX (mini_pbx): Multi-tenant PBX service with bundled extensions, IVRs, queues, conference bridges, and Ring2All PBX provisioning automation.
Wholesale SIP Trunk (sip_trunk): Dedicated trunking packages with burstable concurrent channel limits, Ring2All SBC dispatching, and per-minute overage rating.
Telecom Bundle / Combo (bundle): Hybrid packages pairing cloud PBX extensions with high-capacity SIP trunking and pooled toll-free/domestic minutes.
Hardware Rental (hardware): Physical equipment leases (e.g. Yealink IP deskphones, ATA gateways) billed as recurring monthly line items.
Custom Elastic Sizing (is_custom_sizing): Dynamic sliding-scale packages allowing customer-selected step increments for channels, extensions, and recording storage.

 ┌────────────────────────────────────────────────────────────────────────┐
 │                        Product Plan (public.plans)                     │
 │  • service_type: 'mini_pbx' | 'sip_trunk' | 'bundle' | 'hardware'      │
 │  • price: NUMERIC(10,2) (e.g. $39.99/mo) | currency: 'USD'            │
 │  • included_extensions: 10 | included_channels: 4                      │
 │  • included_minutes: 1000 | fup_overage_rate_per_min: $0.0150         │
 │  • rate_card_id: FK -> public.rate_cards (Outbound overage deck)       │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
           ┌─────────────────────────┴─────────────────────────┐
           ▼                                                   ▼
 ┌───────────────────────────────────┐               ┌───────────────────────────────────┐
 │     Ring2All PBX Tenant Limits    │               │     Ring2All SBC Channel Policy   │
 │  • Max Extensions: 10             │               │  • Max Concurrent Channels: 4     │
 │  • Max Queues: 2                  │               │  • Trunk Outbound CPS Bounds      │
 │  • Storage Retention: 180 Days    │               │  • Associated Rate Card Routing   │
 └───────────────────────────────────┘               └───────────────────────────────────┘

2. Module Overview (Commercial & Business Value)

Predictable Recurring Revenue (MRR): Turns unpredictable VoIP usage into steady, automated monthly or annual recurring revenue streams.
Automated Tier Enforcement: Automatically provisions and enforces operational resource ceilings in the voice engines, preventing resource starvation or unpaid over-consumption.
Flexible Packaging & Upselling: Supports fixed packages for standard enterprise clients alongside modular elastic plans for high-growth enterprises needing incremental capacity on demand.

3. 🎯 User Roles & Key Capabilities

User Role	Key Permissions	Core Responsibilities & Workflows
Super Administrator	Full Plan Catalog Control	Creates new commercial offerings, defines base margins, approves promotional discounts, and binds default rate cards.
Product Manager	Create & Edit Packages	Configures plan feature bundles (extension tiers, included minutes, recording quotas) and adjusts marketing descriptions.
Billing Analyst	Read & Subscription Ingestion	Reviews customer plan enrollments, tracks MRR performance across catalog SKUs, and handles plan migration requests.
Client Portal Customer	Read & Self-Service Checkout	Browses available packages in the online Plan Store, compares quotas, and subscribes using credit card auto-pay.

4. Visual Interface & Form Structure

4.1 Plans Catalog (List View)

The Product Plans & Packages catalog displays all active and archived service offerings with clear badges indicating service classification, base price, bundled capacities, and subscriber counts.

Plans Catalog List

4.2 Plan Configuration Form (Form View)

The Plan Configuration form manages granular product rules across commercial pricing, voice channel limits, extension allowances, minute bundles, and recording storage quotas.

Plan Configuration Form

4.3 Form Parameter Reference

Parameter Name	Data Type	Required	Default Value	Description & Business Rules
Plan Name	`String`	Yes	—	Marketing title displayed on customer quotes, invoices, and the self-service Plan Store.
Plan Code / SKU	`String`	Yes	—	Unique alphanumeric SKU (e.g. `PBX_PRO_10EXT`). Immutable once associated with active customer subscriptions.
Service Classification	`Enum`	Yes	`mini_pbx`	Classification: `mini_pbx` (Cloud PBX), `sip_trunk` (Trunking), `bundle` (Combined), `hardware` (Lease).
Base Price	`Numeric`	Yes	`0.00`	Recurring subscription price billed at the start of each billing period in the plan’s currency.
Billing Period	`Enum`	Yes	`monthly`	Billing frequency: `monthly`, `quarterly`, `semi_annual`, `annual`.
Included Channels	`Integer`	Yes	`2`	Number of simultaneous call channels provisioned on Ring2All SBC / PBX cores.
Included Extensions	`Integer`	Yes	`0`	Number of SIP extensions permitted within the customer’s Ring2All PBX domain.
Included Minutes	`Integer`	Yes	`0`	Pooled outbound domestic minutes included per cycle before FUP overage pricing begins.
FUP Overage Rate	`Numeric`	Yes	`0.0000`	Per-minute billing rate applied to outbound calls once pooled included minutes are depleted.
Associated Rate Card	`Dropdown`	No	None	Linked rate card used to bill international or off-net destinations not covered by included minutes.
Recording Quota (GB)	`Integer`	Yes	`0`	Bundled audio storage space for call recordings and voicemails before storage overages apply.
Status (Active)	`Boolean`	Yes	`true`	When active, the plan is available for customer assignment and self-service purchasing.

Multimodal AI Package Configuration (3-Block Allowance)

The Plan Configuration form exposes three specialized blocks for packaging and monetizing Artificial Intelligence telephony capabilities:

AI Service Block	Parameter	Data Type	Default	Description & Operational Behavior
AI Chat & Copilot Tokens	`included_ai_tokens`	`BigInt`	`0`	Pooled prompt and completion tokens included per billing cycle for web portal copilot and extension chatbots.
	`ai_token_overage_rate`	`Numeric`	`0.0000`	Retail price charged per 1,000 tokens once the included monthly token allowance is exhausted.
AI Voice Agents	`included_ai_voice_minutes`	`Integer`	`0`	Bundled real-time interactive voice agent minutes per cycle for inbound IVR bots and outbound voice assistants.
	`ai_voice_overage_rate_per_min`	`Numeric`	`0.0000`	Retail per-minute rate applied to interactive voice sessions exceeding the bundled minute allowance.
Audio Transcription (STT)	`included_ai_transcription_minutes`	`Integer`	`0`	Bundled minutes for automatic call recording transcription, voicemail-to-text, and AI executive summaries.
	`ai_transcription_overage_rate_per_min`	`Numeric`	`0.0000`	Retail per-minute rate applied to speech-to-text transcription once included minutes are depleted.

5. Architectural Flow & Subscription Provisioning

   Customer Subscribes to Plan
                 │
                 ▼
 ┌─────────────────────────────────┐
 │     Public Plans Catalog SKU    │
 │  • Service Type: mini_pbx       │
 │  • Price: $49.99/mo             │
 │  • Ext Quota: 20 | Channels: 6  │
 │  • Bundled AI: 500k tokens,     │
 │    100 voice min, 60 STT min    │
 └───────────────┬─────────────────┘
                 │ Triggers Automated Provisioning
                 ▼
 ┌─────────────────────────────────┐
 │     Subscription Activation     │
 ├─────────────────────────────────┤
 │ 1. Ledger Entry: $49.99 debit   │
 │ 2. PBX API: Provision Tenant    │
 │    with 20 extensions limit     │
 │ 3. SBC API: Provision Trunk     │
 │    with 6 max channels          │
 │ 4. OCS: Initialize subscription │
 │    balances for Voice, Tokens,  │
 │    and Audio Transcription      │
 └───────────────┬─────────────────┘
                 │
                 ▼
 ┌────────────────────────────────────────────────────────┐
 │           Real-Time OCS Multimodal Rating Run          │
 ├────────────────────────────────────────────────────────┤
 │ When an AI session or call completes:                  │
 │ 1. Ingest usage (tokens, duration, service type)       │
 │ 2. Check active subscription bundle balance:           │
 │    • If balance > 0: Deduct atomically (Billed = $0)   │
 │    • If balance = 0: Apply overage rate from plan      │
 │ 3. Debit customer prepaid wallet if overage occurs     │
 │ 4. Generate auditable AIDR record                      │
 └────────────────────────────────────────────────────────┘

6. Common Scenarios & Operational Playbooks

Scenario A: Creating an Elastic Sized SIP Trunking Plan

Navigate to Services & Rates → Plans (Catalog) and click + Add Plan.
Set Service Classification to sip_trunk and enter SKU TRUNK_ELASTIC_BASE.
Set base price to $25.00/mo with 4 included channels.
Toggle Enable Custom Sizing and configure channel_step = 2 at $10.00 per step.
In Associated Rate Card, select the wholesale outbound termination rate card.
Click Save Plan. The plan appears in the online catalog ready for customer self-service subscription.

Scenario B: Retiring / Archiving an Obsolete Plan Tier

Locate the outdated plan in the catalog table and open the editor.
In the status section, toggle Active Status from Active to Archived / Inactive.
Save changes. Existing active subscribers continue on their grandfathered rate, but the plan is hidden from the public Plan Store and new manual account assignments.

7. Troubleshooting & Diagnostic Commands

Querying Catalog Plans & Quota Configurations (PostgreSQL)

su - postgres -c "psql -d ss_billing -c \"
SELECT id, name, code, service_type, price, included_extensions,
       included_channels, included_minutes, is_active
FROM plans
ORDER BY id ASC;\""

Checking Plan Details via REST API

curl -s -k -X GET "https://192.168.10.29/api/v1/plans/1" \
  -H "Authorization: Bearer <TOKEN>" | jq .

8. Model Context Protocol (MCP) AI Integration

The Plans & Packages Catalog module connects natively to the Ring2All BSS MCP Server, allowing autonomous AI agents and billing operators to query commercial offerings, inspect quota parameters, and audit active customer subscriptions.

Available MCP Tools

Tool Name	Access Role	Description & Primary Function	Example Arguments
`list_billing_plans`	`Billing Operations` / `Admin`	Lists available SaaS plans, trunk packages, recurring prices, and quotas.	`{"status": "active"}`
`get_billing_plan`	`Billing Operations` / `Admin`	Retrieves detailed plan configuration including included extensions, channels, and rate cards.	`{"planId": "1"}`
`list_active_subscriptions`	`Billing Operations` / `Admin`	Lists active recurring customer subscriptions, renewal dates, and quantities.	`{"customerId": "1"}`

Sample MCP Tool Execution: `get_billing_plan`

Request Payload

{
  "name": "get_billing_plan",
  "arguments": {
    "planId": "1"
  }
}

Response Payload

{
  "id": "1",
  "name": "Business PBX Starter",
  "code": "PBX_START_10EXT",
  "serviceType": "mini_pbx",
  "price": "$39.99",
  "currency": "USD",
  "billingPeriod": "monthly",
  "includedExtensions": 10,
  "includedChannels": 4,
  "includedMinutes": 1000,
  "includedStorageGb": 10,
  "fupOverageRate": "$0.0150/min",
  "rateCard": "Standard Retail Rate Card",
  "active": true
}

Conversational AI Prompts for Copilot

“List all active PBX plans and compare their included extensions and monthly prices.”
“Show detailed configuration and included channels for plan SKU PBX_START_10EXT.”
“Which active subscriptions are currently renewing for customer 1?”

9. Glossary

MRR (Monthly Recurring Revenue): Predictable total revenue generated by all active subscriptions every 30 days.
FUP (Fair Usage Policy): Terms governing acceptable use of “unlimited” or bundled minute pools, triggering per-minute rates upon quota exhaustion.
Elastic Sizing: Commercial packaging model that scales dynamically based on customer-selected channel and extension increments.
Rate Card Binding: Associating a destination tariff matrix to a subscription for rating non-inclusive calls.
Model Context Protocol (MCP): Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.