Rate Cards & LCR Costs Module Documentation

Table of Contents

1. Module Overview (Technical)
2. Module Overview (Commercial & Business Value)
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Form Structure
5. Architectural Flow & Longest-Prefix-Match Rating
6. Common Scenarios & Operational Playbooks
7. Troubleshooting & Diagnostic Commands
8. Model Context Protocol (MCP) AI Integration
9. Glossary

---

1. Module Overview (Technical)

The Rate Cards & LCR Costs module (public.rate_cards and public.rates) powers the high-speed rating engine and margin calculator of Ring2All Billing. It ingests, organizes, and evaluates destination tariff decks for both wholesale carrier termination costs (Buy decks) and enterprise retail customer rates (Sell decks).

Longest-Prefix-Match (LPM) Evaluation Engine

When an outbound call is placed, the rating engine evaluates the destination E.164 dialed digits (e.g. +13055550199) against the active rate card table using an indexed B-tree Longest Prefix Match algorithm:

1. Exact match test: 13055550199
2. Area code match test: 1305
3. Country code match test: 1
4. Default fallback deck: *

 Dialed Destination: +44 20 7946 0991 (London, UK)
                     │
                     ▼
 ┌────────────────────────────────────────────────────────┐
 │           Prefix Matching Evaluation Order             │
 ├───────────────────┬──────────────┬─────────────────────┤
 │ Prefix Checked    │ Match Found? │ Applied Action      │
 ├───────────────────┼──────────────┼─────────────────────┤
 │ 442079460991      │ No           │ Continue evaluation │
 │ 442079            │ No           │ Continue evaluation │
 │ 4420 (London)     │ YES (Exact!) │ Apply Rate: $0.0120 │
 │ 44 (UK National)  │ Skipped      │ (LPM takes priority)│
 └───────────────────┴──────────────┴─────────────────────┘

Rate Structure & Billing Intervals

Every prefix rate entry specifies:

• Initial Interval (init_interval): The minimum billable seconds upon call answer (typically 1s, 30s, or 60s).
• Increment Interval (next_interval): The rounding quantum for call duration beyond the initial interval (typically 1s or 6s).
• Connection Surcharge (setup_fee): One-off connection cost assessed immediately upon SIP 200 OK.

---

2. Module Overview (Commercial & Business Value)

• Guaranteed Margin Protection: Real-time pairing of wholesale buy decks against customer retail sell decks guarantees that every route yields a positive gross margin before the call is dispatched.
• Least Cost Routing (LCR) Integration: Exports real-time cost matrices to Ring2All SBC’s Kamailio drouting engine, ensuring calls take the highest-quality and lowest-cost carrier transit path.
• CSV Bulk Decks Ingestion: Handles hundred-thousand-row carrier rate deck spreadsheets with sub-minute automated ingestion, duplicate prefix detection, and effective date versioning.

---

3. 🎯 User Roles & Key Capabilities

User Role	Key Permissions	Core Responsibilities & Workflows
Super Administrator	Full Control & Wholesale Approval	Manages master rate decks, reviews margin performance reports, and authorizes wholesale discount tiers.
Telecom Carrier Manager	Upload & Manage Carrier Decks	Uploads vendor rate sheets (Telnyx, Twilio, Bandwidth), monitors carrier price hike notices, and updates effective dates.
Billing Analyst	Read & Customer Assignment	Assigns retail rate decks to customer accounts, verifies rated CDR calculations, and handles billing discrepancies.
NOC Engineer	Read & Routing Verification	Validates prefix matching behavior and checks that destination routing tables match the current rate cards.

---

4. Visual Interface & Form Structure

4.1 Rate Cards Deck (List View)

The Rate Cards list displays all operational buy and sell decks with currency tags, prefix counts, default flags, and duplication tools.

4.2 Rate Card Configuration Form (Form View)

The Rate Card Configuration form enables comprehensive rate deck maintenance, including CSV bulk uploads, currency settings, rounding intervals, and prefix-level rate adjustments.

4.3 Form Parameter Reference

Parameter Name	Data Type	Required	Default Value	Description & Business Rules
Rate Card Name	String	Yes	—	Clear descriptive title (e.g. Standard Retail Rate Card or Telnyx Wholesale Deck).
Classification	Enum	Yes	customer_sell	customer_sell (rates charged to clients) or carrier_buy (wholesale costs paid to transit providers).
Billing Currency	String	Yes	USD	ISO-4217 3-letter currency code (USD, EUR, GBP) governing all per-minute rates in the deck.
Default Initial Interval	Integer	Yes	60	Default minimum billable seconds applied to new prefixes added to this rate card.
Default Increment Interval	Integer	Yes	60	Default second increment applied after initial interval expiration (e.g. 1/1, 30/6, 60/60).
Default Connection Surcharge	Numeric	Yes	0.0000	Fixed charge added to the call cost upon connection, regardless of call duration.
Default Status	Boolean	Yes	false	When true, this card is automatically assigned to new customers who do not have a custom rate card specified.

4.4 AI Model Rate Cards Tab (AiRateCardsTab)

The AI Model Rate Cards tab provides specialized pricing decks for LLM tokens, neural TTS voices, real-time voice agents, and speech-to-text audio transcription.

Architectural Pricing Components

• Provider & Model: Binds rates to certified AI Providers (OpenAI, Anthropic, ElevenLabs, Deepgram) and models (e.g. gpt-4o, gpt-4o-realtime, claude-3-5-sonnet, deepgram-nova-2).
• Wholesale vs. Retail Tracking: Operators define the raw vendor cost alongside the customer retail price.
• Automated Gross Margin: The system automatically calculates and highlights profit margins in real time: $$\text{Margin (%)} = \left(\frac{\text{Retail Price} - \text{Wholesale Cost}}{\text{Retail Price}}\right) \times 100$$

AI Rate Card Parameter Reference

Tariff Dimension	Unit Basis	Description
Prompt Tokens	Per 1,000 Tokens	Input text tokens processed by the LLM model.
Completion Tokens	Per 1,000 Tokens	Output tokens generated by the LLM model response.
Realtime Voice Blended	Per Minute	Bidirectional interactive audio streaming minutes with AI voice agents.
Audio In / Out Tokens	Per 1,000 Tokens	Direct audio modality tokens consumed in multimodal real-time sessions.
Text-to-Speech (TTS)	Per 1,000 Chars	Neural voice synthesis characters converted to audio speech.
Audio Transcription (STT)	Per Minute	Recorded call audio converted to text and summarized by AI.

---

5. Architectural Flow & Longest-Prefix-Match Rating

              SIP INVITE Received
                      │
                      ▼
         Query Active Customer Profile
                      │
                      ▼
 ┌──────────────────────────────────────────┐
 │    Locate Associated Rate Card (Sell)    │
 └────────────────────┬─────────────────────┘
                      │
                      ▼
 ┌──────────────────────────────────────────┐
 │  Execute Longest-Prefix-Match (LPM)      │
 │  • Search Destination Dialed Digits      │
 │  • Apply (Duration / Increment) * Rate   │
 │  • Assess Connection Setup Fee           │
 └────────────────────┬─────────────────────┘
                      │
                      ▼
 ┌──────────────────────────────────────────┐
 │        Real-Time OCS Rating Event        │
 │  • Calculated Cost: $0.0360              │
 │  • Deduct from Customer Wallet           │
 └──────────────────────────────────────────┘

---

6. Common Scenarios & Operational Playbooks

Scenario A: Importing a Carrier Wholesale Rate Sheet (CSV)

1. Navigate to Services & Rates → Rate Cards and select the vendor buy deck (e.g. Telnyx Wholesale Deck).
2. Click Import CSV Rates.
3. Upload the vendor .csv file with columns mapped: prefix, destination, rate_per_min, init_interval, next_interval.
4. Click Validate & Ingest. The system parses the file, strips non-numeric characters from prefixes, verifies effective dates, and reports row additions.

Scenario B: Creating a High-Margin Retail Deck by Cloning

1. In the Rate Cards list, click the Clone icon next to Standard Retail Rate Card.
2. Enter the new title: Premium Retail Rate Card - 20% Margin.
3. Select Apply Bulk Price Multiplier: 1.20 (+20%).
4. Click Clone Deck. The system creates an exact duplicate with all prefix rates adjusted upward by 20%.

---

7. Troubleshooting & Diagnostic Commands

Inspecting Top Destination Rates in Rate Card (PostgreSQL)

su - postgres -c "psql -d ss_billing -c \"
SELECT r.id, r.prefix, r.destination_name, r.rate_per_min,
       r.init_interval, r.next_interval
FROM rates r
WHERE r.rate_card_id = 23
ORDER BY r.prefix ASC
LIMIT 10;\""

Testing Longest-Prefix Match Query

su - postgres -c "psql -d ss_billing -c \"
SELECT prefix, destination_name, rate_per_min
FROM rates
WHERE rate_card_id = 23
  AND '13055550199' LIKE prefix || '%'
ORDER BY length(prefix) DESC
LIMIT 1;\""

---

8. Model Context Protocol (MCP) AI Integration

The Rate Cards & LCR Costs module connects directly to the Ring2All BSS MCP Server, allowing AI rating copilots, wholesale analysts, and routing engineers to query destination tariffs, test longest-prefix matches, and simulate call costs through conversational interfaces.

Available MCP Tools

Tool Name	Access Role	Description & Primary Function	Example Arguments
list_rate_cards	Billing Operations / NOC	Lists wholesale buy decks and retail sell cards with currency, type, and prefix counts.	{"type": "sell", "limit": 10}
lookup_rate_by_prefix	Billing Operations / NOC	Performs Longest Prefix Match (LPM) rating lookup for dialed E.164 digits.	{"rateCardId": 1, "destination": "+13055550199"}
simulate_call_rating	Billing Operations / NOC	Simulates real-time rating for an answered call given dialed number and duration.	{"destination": "+442079460991", "durationSeconds": 120, "rateCardId": 1}

Sample MCP Tool Execution: lookup_rate_by_prefix

Request Payload

{
  "name": "lookup_rate_by_prefix",
  "arguments": {
    "rateCardId": 1,
    "destination": "+13055550199"
  }
}

Response Payload

{
  "matchedPrefix": "1305",
  "destinationName": "United States - Miami, FL",
  "ratePerMinute": 0.0095,
  "initialInterval": 6,
  "nextInterval": 6,
  "setupFee": 0.0000,
  "rateCard": {
    "id": 1,
    "name": "Standard Retail Rate Card",
    "currency": "USD"
  }
}

Conversational AI Prompts for Copilot

• “What is our current retail rate per minute for calls to London (+4420)?”
• “Simulate the cost of a 15-minute call to +13055550199 under Rate Card 1.”
• “List all active wholesale carrier rate cards currently configured.”
• “Compare the cost of terminating to +5255 between Telnyx and Twilio buy decks.”

---

9. Glossary

• Rate Deck: A structured catalog of telephone destination codes and their corresponding per-minute tariffs.
• LCR (Least Cost Routing): Carrier routing algorithm that dispatches outbound calls to the carrier offering the lowest wholesale cost.
• Initial / Next Interval (e.g. 60/60, 30/6, 1/1): Billing rules defining the minimum answered call duration and subsequent rounding increments.
• LPM (Longest Prefix Match): Algorithmic lookup prioritizing the most specific dialed number string match over general country codes.
• Model Context Protocol (MCP): Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.