---
title: "Plans & Packages Catalog Module Documentation"
description: "Documentation for Plans (Catalog)"
---

## 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 & Subscription Provisioning](#5-architectural-flow-and-subscription-provisioning)
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 **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](/screenshots/billing/services-rates/plans/plans-list.png)

### 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](/screenshots/billing/services-rates/plans/plans-form.png)

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

### Scenario B: Retiring / Archiving an Obsolete Plan Tier
1. Locate the outdated plan in the catalog table and open the editor.
2. In the status section, toggle **Active Status** from `Active` to `Archived / Inactive`.
3. 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)
```bash
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
```bash
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
```json
{
  "name": "get_billing_plan",
  "arguments": {
    "planId": "1"
  }
}
```

#### Response Payload
```json
{
  "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.