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 (one product per service, attached to a key set, with one price per destination-country price_key) collapses to one product.
• 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.included_quantity per metered product
Per-destination roaming	Keyed product: a key_set_id on the product, a price_key on each price and usage event
Family plan pooled allowance	Subscription-level allowance shared across event sources
Mid-cycle plan upgrade	POST /subscriptions/{id}/transition-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", "quantity_source": "METERED", "pricing_model": "VOLUME" }'

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

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

Roaming is one keyed product per service. The set of destination keys lives in a key set; each product opts in via key_set_id, and individual prices carry a price_key matching one of the set's entries. Create the key set once:

Code
curl -X POST https://api.kontorion.eu/v1/key-sets \
  -d '{
    "name": "Roaming destinations",
    "slug": "roaming_destinations",
    "entries": [
      { "key": "DE", "display_name": "Germany" },
      { "key": "US", "display_name": "United States" },
      { "key": "IT", "display_name": "Italy" }
    ]
  }'

Then attach the key set to each roaming product:

Code
curl -X POST https://api.kontorion.eu/v1/products \
  -d '{
    "name": "Roaming Voice",
    "quantity_source": "METERED",
    "key_set_id": "keyset_roaming_destinations"
  }'

curl -X POST https://api.kontorion.eu/v1/products \
  -d '{
    "name": "Roaming Data",
    "quantity_source": "METERED",
    "key_set_id": "keyset_roaming_destinations"
  }'

"Rest of world" is handled by a single set price (is_set_price: true, no price_key): the resolver falls back to it for any key in the set that has no exact-match price, so you only price the destinations that differ from the catch-all rate.

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", "included_quantity": "1000", "rollover_enabled": false }'
curl -X POST https://api.kontorion.eu/v1/plans/plan_magenta_pro/products \
  -d '{ "product_id": "prod_sms", "included_quantity": "1000", "rollover_enabled": false }'
curl -X POST https://api.kontorion.eu/v1/plans/plan_magenta_pro/products \
  -d '{ "product_id": "prod_data", "included_quantity": "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 - a DECLARED-quantity product (no meter; quantity set on the subscription item)
curl -X POST https://api.kontorion.eu/v1/products \
  -d '{ "name": "Magenta Pro Plan Fee", "quantity_source": "DECLARED" }'
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
curl -X POST https://api.kontorion.eu/v1/prices \
  -d '{
    "product_id": "prod_magenta_fee",
    "plan_id": "plan_magenta_pro",
    "plan_version": 1,
    "list_price": "40.00",
    "currency": "EUR",
    "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",
    "plan_version": 1,
    "list_price": "0.10",
    "currency": "EUR",
    "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",
    "plan_version": 1,
    "list_price": "0.005",
    "currency": "EUR",
    "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\",
      \"plan_version\": 1,
      \"list_price\": \"0.026\",
      \"currency\": \"EUR\",
      \"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",
    "plan_version": 1,
    "list_price": "0.50",
    "currency": "EUR",
    "price_key": "US",
    "display_name": "Roaming voice (US)",
    "tiers": [{ "up_to": null, "unit_amount": "0.50" }]
  }'

# Rest of world catch-all - €2.00/min (is_set_price = fallback for any key
# in the set without an exact price; carries no price_key of its own)
curl -X POST https://api.kontorion.eu/v1/prices \
  -d '{
    "product_id": "prod_roaming_voice",
    "plan_id": "plan_magenta_pro",
    "plan_version": 1,
    "list_price": "2.00",
    "currency": "EUR",
    "is_set_price": true,
    "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_unit": "month",
    "billing_interval_count": 1,
    "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",
    "quantity": 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",
    "quantity": 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

Hard caps are built on meter thresholds, not billing milestones. (Billing milestones are percentage-of-contract invoice triggers - POST /subscriptions/{subscriptionId}/milestones with a trigger_type of MANUAL, DATE, or EVENT - a different feature.) A meter carries a list of thresholds; each declares a comparator + value over the meter's evaluated total and an action. When usage crosses the threshold the monitor fires the action - action.kind is one of webhook, slack, or emit_event.

Define the data meter with a threshold that webhooks your network OSS when the customer crosses 25 GB (25,000 MB) in the window:

Code
curl -X POST https://api.kontorion.eu/v1/meters \
  -d '{
    "key": "data_mb",
    "name": "Mobile data (MB)",
    "metric_key": "data_mb",
    "function": "SUM",
    "value_field": "quantity",
    "thresholds": [
      {
        "name": "Lisa - data hard cap 25 GB",
        "comparator": "gte",
        "value": 25000,
        "action": {
          "kind": "webhook",
          "target": "https://oss.carrier.example/throttle-msisdn"
        }
      }
    ]
  }'

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.

Scope note. Kontorion emits the breach signal (the webhook to your OSS) and records the breach (GET /meters/{id}/breaches); actually cutting off the MSISDN happens in the carrier's network. The threshold is currently defined on the meter itself, so it applies to every subscription that consumes the meter - per-subscriber caps with subscriber-specific limits are not yet first-class.

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 included_quantity to a very high number (effectively unlimited) and add a meter threshold whose action.kind is webhook 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 + per-price_key prices, with an is_set_price catch-all)
• 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