---
title: "My Subscriptions & Minute Pools Module Documentation"
description: "Documentation for My Subscriptions"
---

## 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. [Minute Pool Allowance & Applied Rate Cards](#4-minute-pool-allowance--applied-rate-cards)
5. [Exporting Calling Rates (CSV & Excel Formats)](#5-exporting-calling-rates-csv--excel-formats)
6. [Active Capacity, Domain Allocation & Lifecycle Management](#6-active-capacity-domain-allocation--lifecycle-management)
7. [Troubleshooting & Verification](#7-troubleshooting--verification)
8. [Glossary](#8-glossary)

---

## 1. Module Overview (Technical)

The **My Subscriptions** module (`SubscriptionsPage.tsx`, `DownloadRatesModal.tsx`, and `clientService.ts`) serves as the day-2 operational hub for enterprise customers in the **Ring2All Billing Client Portal**. It provides direct visibility into active telecom agreements, allocated Hosted PBX capacity (extensions, channels, cloud storage), minute pool consumption meters, renewal schedules, and live telephony rating decks.

```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

    Client->>API: GET /api/client/subscriptions
    API->>DB: Query subscriptions JOIN plans ON plans.id = plan_id
    DB-->>API: Return active plans, included/used minutes, assigned capacity
    API-->>Client: 200 OK (Subscriptions Array + Real-time Usage)

    opt Inspect & Export Applied Rates
        Client->>API: GET /api/client/subscriptions/:id/rates
        API->>DB: Resolve rate_card_id (Plan -> Customer -> Default Sales Deck)
        API->>DB: Query rates table (prefix, destination, rate_per_minute, increments)
        DB-->>API: Active E.164 Destination Rates
        API-->>Client: 200 OK (Deck Metadata + Rates Array)
        Client->>Client: Generate RFC 4180 CSV / XML Spreadsheet 2003 (.xls)
    end
```

### Architectural Highlights
* **Dynamic SLA Tracking:** Real-time calculation of contracted concurrent channels and SIP extensions with instant synchronization across Sofia profiles and Telephony Server domains.
* **Unified Rating Resolution:** Multi-layered hierarchy resolving plan-specific rate decks, customer-negotiated overrides, and system-wide default wholesale/retail price lists.
* **Client-Side Export Engine:** High-performance, zero-dependency streaming of applied tariffs into RFC 4180 CSV with UTF-8 BOM and native XML Spreadsheet 2003 (`.xls`/`.xlsx`) supporting Microsoft Excel, Apple Numbers, and LibreOffice Calc.

---

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

* **Elimination of Bill Shock:** Transparent minute pool gauges and downloadable destination rate decks ensure clients know exactly which calls are covered under their bundle and the exact per-minute overage costs before dialing.
* **Transparent SLA Accountability:** Enterprise clients can audit their contracted extension count, simultaneous channel limit, and automated renewal dates directly from their self-care dashboard.
* **Reduced Billing Support Overhead:** Providing instant CSV and Excel exports of applied calling rates saves tier-1 support teams hundreds of hours typically spent responding to rate inquiry tickets.
* **Frictionless Upsell Pathways:** Context-sensitive links guide users toward upgrading channel capacity or expanding their minute pool when consumption reaches peak thresholds.

---

## 3. 🎯 User Roles & Key Capabilities

| User Role | Primary Objectives | Key Capabilities in My Subscriptions |
| :--- | :--- | :--- |
| **Enterprise Telecom Manager** | Oversees corporate voice infrastructure and trunking quotas. | Audits active mini-PBX seats, verifies simultaneous channel allocations, and monitors minute pool depletion. |
| **Procurement & Finance Officer** | Audits telecommunications expenditure and contract commitments. | Downloads applied destination rates in Excel/CSV, reviews monthly recurring fees, and tracks billing cycle renewal dates. |
| **PBX Administrator** | Configures internal phone extensions and trunk routing. | Verifies connected realm domains (`domain_x.ring2all.local`) and matches subscription capacity against physical handset deployments. |
| **Carrier Operations (NOC)** | Ensures carrier margin and rating integrity. | Configures underlying rate cards linked to retail plans, ensuring positive billing margin on PSTN terminations. |

---

## 4. Minute Pool Allowance & Applied Rate Cards

Subscriptions associated with minute allowances (e.g., *Cloud Mini-PBX Business Pro* with 1,000 included minutes) display an active progress bar indicating used versus total included minutes.

![My Subscriptions Overview](/screenshots/billing/client/subscriptions/subscriptions-list.png)

### Key Display Elements

* **Active Contracts KPI:** Total count of live, recurring telecom service subscriptions tied to the client account.
* **Total Extensions KPI:** Aggregate count of provisioned extensions across all active Hosted PBX domains.
* **Concurrent Channels KPI:** Total simultaneous SIP voice channels authorized for inbound and outbound media traversal.
* **Monthly Commitment KPI:** Total recurring monthly expenditure across all contracted plans.
* **Minute Pool Progress Bar:** Visual bar with percentage indicator (e.g., `245 / 1,000 min (24.5%)`) illustrating usage within the current billing period.
* **Service Capacity Details:** Explicit listing of extensions (`15 ext`) and channels (`4 Channels`) provisioned on the core PBX.

---

## 5. Exporting Calling Rates (CSV & Excel Formats)

For plans including destination minute buckets or customized overage rates, clients can click the **Download Rates** button in the Minute Pool column or the **Rates** action button to launch the **Applied Calling Rates & Coverage** modal.

![Download Applied Rates Modal](/screenshots/billing/client/subscriptions/download-rates-modal.png)

### Export Features & Format Support

1. **RFC 4180 CSV Export:**
   * Generates a clean comma-separated values file encoded with a **UTF-8 BOM (`\uFEFF`)**, preventing character corruption in Microsoft Excel across Windows and macOS.
   * Includes headers: `Prefix`, `Destination Name`, `Country Code`, `Rate Per Min (USD)`, `Connection Fee (USD)`, `Init Increment (sec)`, `Sub Increment (sec)`, and `Plan Minute Pool Coverage`.

2. **Microsoft Excel XML Spreadsheet 2003 (`.xls` / `.xlsx`):**
   * Produces a fully styled workbook with formatted column widths, continuous borders, bold headers with dark fill (`#0F172A`), and typed numeric currency cells (`$#,##0.0000`).
   * Highlights included destination coverage with emerald styling (`#ECFDF5` background with `#047857` bold text).

3. **Live Search Filter:**
   * Dynamic prefix and destination search input allows immediate filtering of countries (e.g., `United States`, `Mexico`, `Colombia`, `Spain`, `United Kingdom`) or international dialing prefixes (`1`, `52`, `57`, `34`, `44`).

---

## 6. Active Capacity, Domain Allocation & Lifecycle Management

Subscriptions link client billing accounts with multi-tenant voice domains on the core switchboard:

| Subscription Parameter | Technical Description | Enforcement Engine |
| :--- | :--- | :--- |
| **Plan & Service** | Name and unique SKU code of the contracted telephony package. | Database catalog (`plans.code`). |
| **Assigned Capacity** | Maximum extension seats and concurrent audio channels. | Ring2All PBX Tenant Quota & Sofia Profile Channel Limiter. |
| **Domain Name** | Dedicated PBX realm (`external_id` / `domain_8`). | Telephony Server SIP Domain Directory (`directory/default`). |
| **Period & Renewal** | Billing start and end timestamps, including automatic rollover date. | OCS Recurring Billing Sweep Cron (`sweeperService.ts`). |
| **Monthly Fee** | Contracted base price billed every month. | Digital Wallet deduction or automated credit card charge. |
| **Cancellation** | Self-service plan termination action with confirmation modal. | Fastify API endpoint `POST /api/client/subscriptions/:id/cancel`. |

---

## 7. Troubleshooting & Verification

### Verifying Rate Card Mapping
To verify that a client subscription correctly maps to an active rate deck in PostgreSQL:
```sql
SELECT 
    s.id AS subscription_id,
    c.name AS customer_name,
    p.name AS plan_name,
    p.included_minutes,
    rc.name AS applied_rate_card,
    rc.currency,
    COUNT(r.id) AS total_rates_mapped
FROM subscriptions s
JOIN customers c ON c.id = s.customer_id
JOIN plans p ON p.id = s.plan_id
LEFT JOIN rate_cards rc ON rc.id = COALESCE(p.rate_card_id, (
    SELECT rate_card_id FROM customer_rate_cards WHERE customer_id = c.id LIMIT 1
))
LEFT JOIN rates r ON r.rate_card_id = rc.id AND r.is_active = TRUE
WHERE s.id = 9
GROUP BY s.id, c.name, p.name, p.included_minutes, rc.name, rc.currency;
```

### Inspecting Client Rates via REST API
```bash
curl -k -s -X GET "https://192.168.10.29/api/client/subscriptions/9/rates" \
  -H "Authorization: Bearer <CUSTOMER_JWT_TOKEN>" | jq .
```

---

## 8. Glossary

* **Minute Pool:** A pre-purchased block of voice call minutes included in a monthly subscription, decremented as outbound calls are rated by the OCS.
* **Rate Card (Tarifario):** An organized collection of destination prefixes, per-minute tariffs, connection fees, and billing increments used by the rating engine.
* **Initial Increment (Init Increment):** The minimum billable call duration in seconds applied to the first block of a connected conversation (e.g., 6 seconds or 60 seconds).
* **Subsequent Increment (Sub Increment):** The recurring time block in seconds used to calculate charges for call duration beyond the initial increment.
* **UTF-8 BOM:** A 3-byte signature (`EF BB BF`) prepended to CSV text files to instruct Microsoft Excel to interpret international character encodings correctly.