Copy page

Business models

Telecom / Mobile Carrier

The telecom pattern is one of the most operationally complex in commercial billing - carriers run prepaid wallet balances, postpaid recurring plans, included allowances per metered dimension, per-destination-country roaming pricing, family-plan pooled allowances, and overage handling, all inside a single subscription. Every primitive in Kontorion shows up somewhere in a carrier's billing model.

Real-world examples. T-Mobile, Vodafone, Verizon, AT&T, Free Mobile, Vodafone Italy, Telekom Deutschland, Orange, O2, Three UK, Mint Mobile. Common shape: monthly plan with X minutes + Y SMS + Z GB included, additional usage at per-unit rates, roaming priced per destination country and per service type, family plan with pooled allowance across N lines, prepaid option with topup-and-spend wallet model.

The shape of the problem

Telecoms hit nearly every operational complexity dimension at once:

• Prepaid + postpaid coexistence. The same carrier offers customer-funded wallet balances (prepaid SIMs - load €20, talk until empty) and monthly recurring plans (postpaid - bill at the end of the month). Often one customer has both.
• Multi-dimensional metered allowances. A single plan includes minutes, SMS, and data, each with their own allowance and own overage rate. Real-time visibility per dimension is non-negotiable.
• Roaming as keyed pricing. International roaming charges per destination country and per service (call vs SMS vs data). Modeling each as a separate product creates 200+ entries per service; modeling roaming as a keyed product (key = destination country + service) collapses to one.
• Family plans / pooled allowances. A family plan has 5 lines but shares a pooled allowance for data; minutes might be per-line. Pool semantics live at the subscription level, per-line semantics at the line level.
• Real-time hard caps. Customers expect to be able to set "stop me from using more than 5 GB this month" caps that actually enforce in real time, not "send me an invoice after the fact."
• Mid-cycle plan changes. Upgrading from a 5GB plan to a 20GB plan mid-cycle triggers immediate access to the new allowance (less the consumed portion of the old one) and prorated billing.

Kontorion blueprint

Concern	Kontorion primitive
Prepaid SIM balance	Wallet per customer; debit per usage event
Monthly recurring plan	Standard subscription with metered products
Per-dimension allowance	PlanVersionProduct.allowance per metered product
Per-destination roaming	Keyed product keyed on country_iso + service
Family plan pooled allowance	Subscription-level allowance shared across event sources
Mid-cycle plan upgrade	PATCH /subscriptions/{id}/plan with proration

Build it

1. Define the metered products

Code
# Voice minutes
curl -X POST https://api.kontorion.eu/v1/products \
  -d '{ "name": "Voice", "type": "USAGE", "pricing_model": "VOLUME" }'

# SMS
curl -X POST https://api.kontorion.eu/v1/products \
  -d '{ "name": "SMS", "type": "USAGE", "pricing_model": "VOLUME" }'

# Data
curl -X POST https://api.kontorion.eu/v1/products \
  -d '{ "name": "Mobile Data", "type": "USAGE", "pricing_model": "VOLUME" }'

# Roaming - one keyed product per service, key = destination country
curl -X POST https://api.kontorion.eu/v1/products \
  -d '{
    "name": "Roaming Voice",
    "type": "USAGE",
    "price_key_label": "destination_country",
    "default_price_key": "ROW",
    "unmatched_price_key_policy": "use_default"
  }'

curl -X POST https://api.kontorion.eu/v1/products \
  -d '{
    "name": "Roaming Data",
    "type": "USAGE",
    "price_key_label": "destination_country",
    "default_price_key": "ROW",
    "unmatched_price_key_policy": "use_default"
  }'

ROW = "rest of world" - the catch-all rate for any country not explicitly priced.

2. Build the postpaid plan with allowances

Code
curl -X POST https://api.kontorion.eu/v1/plans \
  -d '{ "name": "Magenta Pro" }'

# Plan: included voice (1000 min), SMS (1000), data (20 GB), no roaming included
curl -X POST https://api.kontorion.eu/v1/plans/plan_magenta_pro/products \
  -d '{ "product_id": "prod_voice", "allowance": 1000, "rollover_enabled": false }'
curl -X POST https://api.kontorion.eu/v1/plans/plan_magenta_pro/products \
  -d '{ "product_id": "prod_sms", "allowance": 1000, "rollover_enabled": false }'
curl -X POST https://api.kontorion.eu/v1/plans/plan_magenta_pro/products \
  -d '{ "product_id": "prod_data", "allowance": 20000, "rollover_enabled": false }'

# Roaming products - no included allowance, per-call/MB charges from event 1
curl -X POST https://api.kontorion.eu/v1/plans/plan_magenta_pro/products \
  -d '{ "product_id": "prod_roaming_voice" }'
curl -X POST https://api.kontorion.eu/v1/plans/plan_magenta_pro/products \
  -d '{ "product_id": "prod_roaming_data" }'

# Plan flat fee
curl -X POST https://api.kontorion.eu/v1/products \
  -d '{ "name": "Magenta Pro Plan Fee", "type": "FIXED_CHARGE" }'
curl -X POST https://api.kontorion.eu/v1/plans/plan_magenta_pro/products \
  -d '{ "product_id": "prod_magenta_fee" }'

3. Set domestic and overage prices

Code
# Plan flat fee: €40/month
curl -X POST https://api.kontorion.eu/v1/prices \
  -d '{
    "product_id": "prod_magenta_fee",
    "plan_id": "plan_magenta_pro",
    "list_price": { "value": "40.00", "currency": "EUR" },
    "currency": "EUR",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "tiers": [{ "up_to": null, "unit_amount": "40.00" }]
  }'

# Domestic voice overage: €0.10/min above 1000 included
curl -X POST https://api.kontorion.eu/v1/prices \
  -d '{
    "product_id": "prod_voice",
    "plan_id": "plan_magenta_pro",
    "list_price": { "value": "0.10", "currency": "EUR" },
    "currency": "EUR",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "tiers": [{ "up_to": null, "unit_amount": "0.10" }]
  }'

# Domestic data overage: €5.00/GB above 20 GB included (priced per MB internally)
curl -X POST https://api.kontorion.eu/v1/prices \
  -d '{
    "product_id": "prod_data",
    "plan_id": "plan_magenta_pro",
    "list_price": { "value": "0.005", "currency": "EUR" },
    "currency": "EUR",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "tiers": [{ "up_to": null, "unit_amount": "0.005" }]
  }'

4. Set roaming rates per destination country

Code
# Roaming voice within EU - regulated cap rate €0.026/min
for country in DE FR ES IT NL AT BE PL PT GR; do
  curl -X POST https://api.kontorion.eu/v1/prices \
    -d "{
      \"product_id\": \"prod_roaming_voice\",
      \"plan_id\": \"plan_magenta_pro\",
      \"list_price\": { \"value\": \"0.026\", \"currency\": \"EUR\" },
      \"currency\": \"EUR\",
      \"billing_interval\": \"monthly\",
      \"billing_interval_count\": 1,
      \"price_key\": \"$country\",
      \"display_name\": \"Roaming voice ($country)\",
      \"tiers\": [{ \"up_to\": null, \"unit_amount\": \"0.026\" }]
    }"
done

# US roaming - €0.50/min
curl -X POST https://api.kontorion.eu/v1/prices \
  -d '{
    "product_id": "prod_roaming_voice",
    "plan_id": "plan_magenta_pro",
    "list_price": { "value": "0.50", "currency": "EUR" },
    "currency": "EUR",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "price_key": "US",
    "display_name": "Roaming voice (US)",
    "tiers": [{ "up_to": null, "unit_amount": "0.50" }]
  }'

# Rest of world catch-all - €2.00/min
curl -X POST https://api.kontorion.eu/v1/prices \
  -d '{
    "product_id": "prod_roaming_voice",
    "plan_id": "plan_magenta_pro",
    "list_price": { "value": "2.00", "currency": "EUR" },
    "currency": "EUR",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "price_key": "ROW",
    "display_name": "Roaming voice (rest of world)",
    "tiers": [{ "up_to": null, "unit_amount": "2.00" }]
  }'

5. Subscribe a customer

Code
curl -X POST https://api.kontorion.eu/v1/subscriptions \
  -d '{
    "customer_id": "cust_lisa",
    "plan_id": "plan_magenta_pro",
    "billing_interval": "monthly",
    "items": [
      { "product_id": "prod_magenta_fee", "quantity": 1 },
      { "product_id": "prod_voice", "quantity": 1 },
      { "product_id": "prod_sms", "quantity": 1 },
      { "product_id": "prod_data", "quantity": 1 }
    ],
    "metadata": { "msisdn": "+491701234567" }
  }'

6. Network ingests usage events

For every call, SMS, or data session, the carrier's network sends an event:

Code
# Domestic 5-minute call
curl -X POST https://api.kontorion.eu/v1/transaction/usage-event \
  -d '{
    "customer_id": "cust_lisa",
    "subscription_id": "sub_lisa",
    "product_id": "prod_voice",
    "metric_key": "voice_minutes",
    "value": 5,
    "timestamp": "2025-04-15T14:30:00Z",
    "idempotency_key": "cdr_2904815032",
    "metadata": { "called_msisdn": "+491715555555" }
  }'

# Roaming call from Italy to Germany - 3 min
curl -X POST https://api.kontorion.eu/v1/transaction/usage-event \
  -d '{
    "customer_id": "cust_lisa",
    "subscription_id": "sub_lisa",
    "product_id": "prod_roaming_voice",
    "metric_key": "roaming_voice_minutes",
    "price_key": "IT",
    "value": 3,
    "timestamp": "2025-04-16T09:15:00Z",
    "idempotency_key": "cdr_2904815077"
  }'

The first event consumes 5 minutes of the 1,000-minute domestic allowance; the second is roaming-priced from event 1 because roaming products carry no allowance.

7. Hard cap on data with network enforcement

Code
curl -X POST https://api.kontorion.eu/v1/billing-milestones \
  -d '{
    "name": "Lisa - data hard cap 25 GB",
    "customer_id": "cust_lisa",
    "subscription_id": "sub_lisa",
    "condition": {
      "type": "usage_threshold",
      "product_id": "prod_data",
      "metric_key": "data_mb",
      "value": 25000
    },
    "effect": {
      "type": "webhook",
      "webhook_url": "https://oss.carrier.example/throttle-msisdn",
      "payload": { "msisdn": "+491701234567", "action": "block_data" }
    }
  }'

When the customer crosses 25 GB in the period, Kontorion fires the webhook to the network OSS, which blocks further data sessions for that MSISDN until the next cycle. No "I got a $500 surprise bill" support tickets.

Variations

• Prepaid SIM mode. Same products, but no recurring plan - all events charge against a wallet balance. Top-ups credit the wallet via a manual or auto-topup flow.
• Family plan with pooled data. Use a single subscription with multiple metadata.line_id values on each event; aggregator pools them all into the same bucket.
• Unlimited plans with fair-use throttling. Set the data product's allowance to a very high number (effectively unlimited) and use a billing milestone to throttle (not bill overage) when the customer crosses a fair-use threshold.
• Add-on data packs. Customer buys a one-time 5GB pack: post a wallet_credit of 5GB to a data-specific allowance pool that the aggregator consumes before the plan allowance.

What you don't have to build

• Per-dimension allowance bookkeeping with real-time drawdown
• Roaming destination dispatch (keyed product + unmatched_price_key_policy)
• Pooled-allowance family plan accounting
• Hard-cap enforcement webhook integration with the network OSS
• Mid-cycle plan upgrade with prorated allowance and billing
• Reconciliation between CDR ingest and the customer's invoice

Next steps

• Wallets - prepaid SIM balance management
• Pricing - Keyed Prices - per-destination roaming rates
• Plans - allowances, pooled buckets, multi-product bundles