Skip to main content

​
MCC/MNC override model

Pricing and rate resolution describes how a per-operator price is attributed. This page is the model behind its strongest rule: the per-(organization, operator) override — a fixed price your organization publishes for one mobile network, applied verbatim ahead of every markup-based rule. Read this page before you manage negotiated rates: it covers what an override record is, which send paths honor it, where to read its effect, and the limits the write path enforces. The task-level walkthrough (create, review, import, delete) lives in MCCMNC overrides.

​
The two pricing planes

Every priced destination exists on two planes at once:
  • Headline pricing — the platform rate card: the published per-operator cost multiplied by a markup, plus the country-level ladder for generic channels. This plane is the same for every organization.
  • Effective pricing — the headline number after your organization’s own rules apply: a verbatim per-operator override first, then your organization-wide markup, then the platform default.
An operator needs both views. The headline plane is what a prospect or an unauthenticated caller sees and what a sales conversation quotes. The effective plane is what your wallet is actually charged, and the only plane your reconciliation loop can rely on. Overrides are the mechanism that moves a network from the headline plane onto your effective plane — the model on this page is what guarantees the movement is exact, bounded, and auditable.

​
Resolution background

When a send carries a resolved destination operator, a network lookup maps the recipient’s number to an MCC/MNC pair, and the pricing resolver runs the per-operator precedence: an override row first, then operator cost × your organization’s markup, then operator cost × the platform default, then no published rate. Both the display path (the rate card) and the charge path (the wallet debit) run the same ladder, so a labeled row on the card names the rule you are billed under. The override record below is the input to step one of that ladder. Voice lanes resolve through the equivalent per-prefix ladder, so an override concept applies to any channel whose lanes are keyed to a specific destination network.

​
The override record

An override is a single row binding:
  • Your organization and one mobile network (the MCC/MNC pair, stored in canonical zero-padded form — MCC + MNC padded to three digits each, so the resolver’s lookup key matches what you entered).
  • A fixed customer-facing price — a rate_per_unit decimal and an ISO-4217 currency, plus optional effective_from / effective_to bounds and a notes field that carries the change-control reason.
One row per (organization, network) pair. Creating a second row for a pair that is already overridden returns 409; update the existing row instead. Two behaviors define the record:
  1. Precedence — the resolver consults the override before any markup rule. The price is applied verbatim: the resolved customer price is the override rate, with no markup layered on top and no further ladder consulted. On the rate card that row reads pricing_source: absolute_override.
  2. Channel scope — the public SMS surface (GET /api/v1/pricing/mccmnc-rates and POST /api/v1/billing/mccmnc-overrides) writes and reads SMS-scoped overrides. Per-channel resolution is explicit in the pricing model — an override bound to one channel never leaks into another — so an unauthorized channel match cannot reprice a send. Channels without a per-operator lane (the generic country-level ladder) never match an operator override at all, and per-channel wildcard markup overrides are a separate record class covered on the rate-resolution page.
Manage the records through POST /api/v1/billing/mccmnc-overrides and its list/update/delete siblings, or through Billing → MCCMNC Overrides in the dashboard. Writes are role-gated to owner and admin; reads are open to any member of your organization. Every write records the before/after state and the stated reason to the pricing change trail.

​
Reading the effective price

Three surfaces separate override from default pricing for a destination:
  • The SMS rate card — GET /api/v1/pricing/mccmnc-rates returns one row per operator with a pricing_source label: absolute_override when a verbatim override supplies the price, org_markup or default_markup when a markup rule does, and null when no published rate exists. In the dashboard this renders under Billing → SMS rates.
  • The what-if simulator — POST /api/v1/pricing/whatif-simulate replays a window of your own traffic against a candidate rate card, so you can size the delta an override will create before you commit it.
  • The cost estimate — GET /api/v1/pricing/estimate?channel=sms&to=… previews the resolved per-unit rate for one destination, the same resolution the send path runs.
For a worked example of consuming the labeled rate card in a reconciliation script, see the MCCMNC overrides guide.

​
Guarantees and limits

  • Bound, never waived. A write that lands a rate below the platform’s active wholesale cost for that operator is rejected (422), so a below-cost override can never bill you less than Orbit pays upstream. A zero or negative rate is rejected at the form level — overrides bound a price, they never emit zero-cost sends. When no wholesale cost row exists for the operator, there is no oracle to compare against and the bound is skipped.
  • Estimate equals charge. The billing estimate and the wallet debit run the same resolution ladder against the same override records, so a previewed price is the charged price. The reconciliation surfaces on CDR export & billing reconciliation — per-call records and per-message usage counters — close that loop for your finance stack.
  • Tenant-scoped by construction. Reads are pinned to your organization and writes to your organization’s rows; cross-organization identifiers return an ordinary not-found rather than confirming a row exists.

​
Change-management semantics

An override applies to the next send priced after the write. Create, update, and delete all invalidate the cached override entry immediately, so there is no cache window to wait out. Sends already in flight keep the rate resolved when they priced — a later override change never rewrites an established ledger row. Deleting an override reverts the network to the markup planes from that point on, and the reverted-from rate stays on the change trail for review.