---
title: "Plan Store & Self-Service Checkout Module Documentation"
description: "Documentation for Plan Store"
---

## 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. [Plan Catalog & Multi-Tier Filter Navigation](#4-plan-catalog--multi-tier-filter-navigation)
5. [Elastic Sizing & Interactive Checkout Modal](#5-elastic-sizing--interactive-checkout-modal)
6. [Instant Tenant Domain & SIP Trunk Provisioning Handshake](#6-instant-tenant-domain--sip-trunk-provisioning-handshake)
7. [Troubleshooting & Verification](#7-troubleshooting--verification)
8. [Glossary](#8-glossary)

---

## 1. Module Overview (Technical)

The **Plan Store** module (`PlanCatalogPage.tsx`, `SubscribePlanModal.tsx`, and `clientService.ts`) enables clients in the **Ring2All Billing Client Portal** to browse public telecom service tiers, customize voice capacity (extensions, simultaneous channels, recording storage), and complete instant self-service activations backed by multi-tenant provisioning.

```mermaid
sequenceDiagram
    autonumber
    actor Client as Customer Portal
    participant API as Ring2All Billing API
    participant DB as PostgreSQL (ss_billing)
    participant Core as Ring2All Core (PBX & SBC)

    Client->>API: GET /api/client/plans/catalog
    API->>DB: SELECT * FROM plans WHERE is_active = true ORDER BY price ASC
    DB-->>API: Active retail service plans
    API-->>Client: 200 OK (Catalog with steps, pricing & features)

    Client->>API: POST /api/client/subscriptions { planId, domainName, customExtensions, customChannels }
    API->>DB: Verify customer wallet balance & anti-fraud quotas
    API->>Core: Provision Tenant Domain (Telephony Server Directory / Sofia Profile)
    API->>Core: Provision SIP Account / Trunk (Kamailio SBC Dispatcher)
    API->>DB: INSERT INTO subscriptions (status='active', external_id=domain)
    DB-->>API: Subscription ID & Timestamps
    API-->>Client: 201 Created (Instant Activation & Realm URL)
```

### Key Technical Capabilities
* **Dynamic Step Pricing:** Calculates prices in real time based on configured step increments (e.g., `+$10.00 / 5 ext` and `+$5.00 / 2 ch`) for elastic PBX plans.
* **Instant Handshake Orchestration:** Automatically provisions voice domains on Telephony Server and registers SIP endpoints on the perimeter SBC without human intervention.
* **Multi-Category Filtering:** Client-side category filtering seamlessly segments plans into **All Services**, **Hosted PBX**, **SIP Trunks**, and **Combo Bundles**.

---

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

* **Zero-Touch Sales Pipeline:** Converts prospects into paying, connected voice subscribers in under 2 minutes through automated digital onboarding.
* **Flexible Elastic Sizing:** Allows corporate clients to right-size their telephony spend by choosing exact extension bundles and voice channel capacity.
* **Hardware & Hardware-as-a-Service (HaaS) Monetization:** Supports leasing IP deskphones (e.g., *Yealink T46U*) bundled into monthly subscription invoices.
* **Predictable Recurring Cash Flow:** Plans automatically renew on monthly or yearly schedules, with recurring charges deducted directly from prepaid digital wallets or authorized credit cards.

---

## 3. 🎯 User Roles & Key Capabilities

| User Role | Primary Objectives | Key Capabilities in Plan Store |
| :--- | :--- | :--- |
| **New Customer / Onboarding Client** | Evaluates voice service tiers and activates corporate telephony. | Browses catalog, compares feature sets, selects custom capacities, and completes initial subscription setup. |
| **Enterprise Account Owner** | Expands communications capacity for growing branch offices. | Provisions additional Hosted PBX domains, increases SIP trunk concurrency, and orders supplementary hardware rentals. |
| **Product & Commercial Manager** | Designs and publishes market-competitive telephony tiers. | Configures base prices, extension step ratios, included minutes, and promotional badges via the Admin Catalog view. |
| **Billing Specialist** | Ensures accurate invoicing and automated renewal cycles. | Verifies that catalog activations trigger automated pro-rated billing entries and digital wallet debits. |

---

## 4. Plan Catalog & Multi-Tier Filter Navigation

The Plan Store interface provides a clean, responsive procurement grid with interactive search and category filtering chips.

![Plan Store Catalog](/screenshots/billing/client/plan-store/plan-store-catalog.png)

### Catalog Navigation Components

* **Category Filter Chips:**
  * **All Services (5):** Full view across all published voice, trunking, and hardware tiers.
  * **Hosted PBX (2):** Cloud-hosted multi-tenant PBX systems with virtual extensions, IVR, voicemail, and ring groups.
  * **SIP Trunk (1):** High-capacity wholesale voice trunking for on-premise IP-PBXs.
  * **Combo Bundle (1):** Unified solutions pairing cloud PBX instances with dedicated PSTN minute pools and hardware deskphones.
* **Service Badges:** Color-coded badges indicating service architecture: `HOSTED PBX` (green), `SIP TRUNK` (blue), `COMBO BUNDLE` (purple), and `ELASTIC SIZING` (cyan).
* **Live Search Bar:** Instant filtering by plan title, SKU code (`PBX_PRO_10EXT`, `SIP_TRK_20CH`), or descriptive capabilities.

---

## 5. Elastic Sizing & Interactive Checkout Modal

Clicking **Configure Plan** or **Activate Plan** launches the checkout modal, enabling immediate plan configuration and multi-engine provisioning.

![Plan Checkout Modal](/screenshots/billing/client/plan-store/plan-checkout-modal.png)

### Checkout Parameters & Sizing Controls

| Parameter | Type | Description |
| :--- | :--- | :--- |
| **Plan Selection** | Display | Name of the plan being activated (e.g., *Yealink T46U IP Deskphone Rental* or *Cloud Mini-PBX Business Pro*). |
| **Capacity Summary** | Display | Included extensions (`10 Extensions`), concurrent channels (`2 Channels`), and cloud storage. |
| **Monthly Service Total** | Dynamic Price | Calculated recurring charge per billing period (e.g., `$12.00 / MO` or `$39.99 / MO`). |
| **Domain Identifier** | Input | Desired PBX subdomain realm (e.g., `acme.ring2all.local`) allocated upon creation. |
| **Action Confirmation** | Button | **Activate & Provision Service** triggers the backend provisioning handshake and creates the billing subscription. |

---

## 6. Instant Tenant Domain & SIP Trunk Provisioning Handshake

When a client activates a plan from the Plan Store:

1. **Anti-Fraud & Balance Verification:**
   * For prepaid accounts, the system verifies sufficient wallet balance to cover the first billing cycle.
2. **PBX Multi-Tenant Realm Creation:**
   * Allocates a dedicated PostgreSQL domain record in `ring2all_pbx` with the specified extension and queue limits.
3. **Sofia Profile SIP Directory Sync:**
   * Generates dynamic Sofia profile XML bindings so that extensions registered under `@domain.ring2all.local` are instantly recognized by Telephony Server.
4. **Perimeter SBC Route Injection:**
   * Registers client trunk credentials with Kamailio's `drouting` and dispatcher tables, enforcing concurrent call limits based on contracted channels.
5. **Subscription Ledger Insertion:**
   * Creates an active record in `ss_billing.subscriptions` with `status = 'active'`, starting the automated recurring billing clock.

---

## 7. Troubleshooting & Verification

### Checking Catalog Items in PostgreSQL
```sql
SELECT 
    id,
    name,
    code,
    service_type,
    price,
    currency,
    billing_period,
    is_custom_sizing,
    included_extensions,
    included_channels,
    included_minutes,
    is_active
FROM plans
WHERE is_active = TRUE
ORDER BY price ASC;
```

### Validating Catalog API Endpoint
```bash
curl -k -s -X GET "https://192.168.10.29/api/client/plans/catalog" \
  -H "Authorization: Bearer <CUSTOMER_JWT_TOKEN>" | jq .
```

---

## 8. Glossary

* **Elastic Sizing:** A dynamic billing model allowing clients to expand extensions and channel quotas in discrete step units with automatic price recalculation.
* **Hosted PBX:** A cloud-based private branch exchange system providing virtual call center and telephony capabilities without on-site hardware.
* **SIP Trunk:** A virtual voice pipe running over IP connecting an external PBX or VoIP system to the public switched telephone network (PSTN).
* **Sofia Profile:** The SIP signaling and media engine module in Telephony Server responsible for SIP registration, authentication, and RTP proxying.
* **Provisioning Handshake:** Automated inter-service communication protocol creating user accounts, routing rules, and credentials across multiple telecom subsystems.