My Subscriptions & Minute Pools Module Documentation

Table of Contents

1. Module Overview (Technical)
2. Module Overview (Commercial & Business Value)
3. 🎯 User Roles & Key Capabilities
4. Minute Pool Allowance & Applied Rate Cards
5. Exporting Calling Rates (CSV & Excel Formats)
6. Active Capacity, Domain Allocation & Lifecycle Management
7. Troubleshooting & Verification
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.

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.

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.

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:

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

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.