---
title: "Rate Cards & LCR Costs Module Documentation"
description: "Documentation for Rate Cards"
---

## 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 & Longest-Prefix-Match Rating](#5-architectural-flow--longest-prefix-match-rating)
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 **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.

![Rate Cards List View](/screenshots/billing/services-rates/rate-cards/rate-cards-list.png)

### 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.

![Rate Card Configuration Form](/screenshots/billing/services-rates/rate-cards/rate-cards-form.png)

### 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)
```bash
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
```bash
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
```json
{
  "name": "lookup_rate_by_prefix",
  "arguments": {
    "rateCardId": 1,
    "destination": "+13055550199"
  }
}
```

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