Pricing

Estimate a send end-to-end

The generated operations below this overlay each document one call; a send decision chains three of them. This section is that round trip in order: look up the lane’s per-message rate, cost a planned campaign from a stored segment’s size, cost one composed body with its segmentation, then read the numbers against the rounding rules.

Step 1 — Look up a destination country and channel

GET /api/v1/pricing/messaging returns the per-unit rate for every message channel in one ISO alpha-2 country, with your organization’s effective price already folded in. effectiveRatePerUnit is the per-message number the wallet debits on that lane; unit says how it meters (per_message for SMS and MMS). The country query is a price-lookup key only — it never routes traffic. The full per-channel walk, including the $0 bring-your-own-credential rows, is §8 below.

curl -X GET "https://api.orbit.devotel.io/api/v1/pricing/messaging?country=US" \
  -H "X-API-Key: $ORBIT_API_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/pricing/messaging?country=US",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const { data } = await res.json();
const sms = data.channels.find((c) => c.channel === "sms");
console.log(sms.effectiveRatePerUnit, sms.currency, sms.unit);

import os, requests

r = requests.get(
    "https://api.orbit.devotel.io/api/v1/pricing/messaging",
    params={"country": "US"},
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
sms = next(c for c in r.json()["data"]["channels"] if c["channel"] == "sms")
print(sms["effectiveRatePerUnit"], sms["currency"], sms["unit"])

200

{
  "data": {
    "country": "US",
    "channels": [
      {
        "channel": "sms",
        "countryCode": "US",
        "direction": "mt",
        "baseRatePerUnit": 0.0165,
        "effectiveRatePerUnit": 0.0181,
        "currency": "USD",
        "unit": "per_message",
        "hasCustomRate": false,
        "provider": "devotel"
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:00.000Z"
  }
}

Step 2 — Cost a planned campaign

A stored segment already knows its audience: GET /api/v1/segments/{id} returns member_count next to the segment object. Multiply it by the step-1 rate and apply the same round-up the wallet uses.

curl -X GET "https://api.orbit.devotel.io/api/v1/segments/seg_01HZY8EXAMPLE" \
  -H "X-API-Key: $ORBIT_API_KEY"

import os, requests

r = requests.get(
    "https://api.orbit.devotel.io/api/v1/segments/seg_01HZY8EXAMPLE",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
print(r.json()["data"]["member_count"])

200

{
  "data": {
    "segment": {
      "id": "seg_01HZY8EXAMPLE",
      "name": "US opt-ins, spring list",
      "member_count": 12480
    },
    "member_count": 12480
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:01.000Z"
  }
}

The campaign price in three lines of Node — the round-up mirrors the wallet’s whole-cent debit from the rounding callout below:

Node.js

const members = 12480; // data.member_count from GET /api/v1/segments/{id}
const rate = 0.0181; // sms.effectiveRatePerUnit from step 1, USD per message
console.log(Math.ceil(members * rate * 100) / 100); // 225.89

12,480 single-segment US messages at $0.0181 project to $225.89. Bodies longer than one segment multiply the rate by the segment count step 3 reports.

Step 3 — What-if a single message

POST /api/v1/messages/estimate is the body-aware companion to GET /api/v1/pricing/estimate: send the exact to and body you plan to send and it segments the body the same way the send path will, then prices through the same resolver the wallet charges with — the quote cannot drift from the charge.

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/estimate" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "channel": "sms",
  "to": "+14155550123",
  "body": "Hi Alex - your order 4417 is out for delivery and should arrive before 6pm today. Track it at ex.co/t/4417 or call 0800 441 417. Reply STOP to opt out of delivery updates."
}'

const res = await fetch("https://api.orbit.devotel.io/api/v1/messages/estimate", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ORBIT_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel: "sms",
    to: "+14155550123",
    body: "Hi Alex - your order 4417 is out for delivery and should arrive before 6pm today. Track it at ex.co/t/4417 or call 0800 441 417. Reply STOP to opt out of delivery updates.",
  }),
});
console.log(await res.json());

import os, requests

r = requests.post(
    "https://api.orbit.devotel.io/api/v1/messages/estimate",
    headers={
        "X-API-Key": os.environ["ORBIT_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "channel": "sms",
        "to": "+14155550123",
        "body": "Hi Alex - your order 4417 is out for delivery and should arrive before 6pm today. Track it at ex.co/t/4417 or call 0800 441 417. Reply STOP to opt out of delivery updates.",
    },
)
print(r.json())

200

{
  "data": {
    "channel": "sms",
    "to": "+14155550123",
    "country": "US",
    "encoding": "GSM-7",
    "segments": 2,
    "rate_per_segment": 0.0181,
    "estimated_cost": 0.0362,
    "currency": "USD"
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:02.000Z"
  }
}

segments × rate_per_segment = estimated_cost: two GSM-7 segments at $0.0181. The sample body runs past the 160-character single-segment limit — the endpoint counts segments the same way the send path splits them. For mms and rcs the response carries no encoding or segments: one flat per-message unit, and estimated_cost equals rate_per_segment.

Step 4 — Currency and rounding rules

Currency. Every price is expressed in its currency — USD unless your lane is priced otherwise; per-org overrides inherit the lane’s currency. Rates resolve per (channel, country, direction) lane, so the number you preview is the number you are billed at.Rounding. Per-unit rates carry sub-cent precision. The wallet debits whole cents, rounded up per message — a 0.825-cent lane bills one cent per message. Estimates quote the unrounded per-unit rate on purpose so you see the true rate; estimated_cost is the rounded-up projection.Segments. SMS bills per segment, not per message: GSM-7 bodies split every 160 characters (153 once concatenated) and UCS-2 unicode bodies every 70 (67 concatenated). A two-segment send costs twice the per-segment rate; POST /api/v1/messages/estimate returns the count before you commit, so a unicode body never surprises you at send time.

The same numbers drive the dashboard: the what-if pricing simulator replays a window of your traffic against a candidate card, and cost intelligence tracks actual spend against projections like the ones above.

Worked pricing samples

The generated blocks below document every parameter and response shape; this overlay walks the three chains a tenant actually runs before a send decision: estimate one destination → read the effective rate sheet → replay traffic against a candidate rate card (the what-if call every sender runs before committing volume), read the current rate card → audit a rate change → explain the delta on a bill, and the operator-level SMS rate card with scope filters team admins use to compare organizations. Every response is the real { data, meta } envelope — data carries the payload, meta carries the request_id and timestamp. Quote meta.request_id when you report a bad number. The Node SDK does not wrap the pricing namespace yet (/pricing/rates in the SDK targets the legacy per-country table, not these tenant routes), so the typed tabs below use the SDK’s orbit.request escape hatch — you get the SDK’s auth, retries, and envelope unwrapping against the raw REST path. Python fronts client.request the same way.

1. Estimate one destination before you send

GET /api/v1/pricing/estimate resolves a single send to the per-unit rate the wallet would actually be charged. Pass channel and a destination to in E.164 form — the endpoint resolves the destination country itself. Add allIn=true to stack the hidden-fee line items (US A2P 10DLC registration, call recording, transcription, premium support) a “what does this lane really cost” question needs; include narrows that list to named surcharge codes.

curl -X GET "https://api.orbit.devotel.io/api/v1/pricing/estimate?channel=sms&to=%2B14155550123&allIn=true" \
  -H "X-API-Key: $ORBIT_API_KEY"

const estimate = await orbit.request(
  "GET",
  "/api/v1/pricing/estimate?channel=sms&to=%2B14155550123&allIn=true",
);
// estimate.data.rate — { ratePerUnit, currency, countryCode }
// estimate.data.allIn.surcharges — itemized hidden fees on the lane

estimate = client.request(
    "GET",
    "/api/v1/pricing/estimate",
    params={"channel": "sms", "to": "+14155550123", "allIn": "true"},
)

200

{
  "data": {
    "channel": "sms",
    "to": "+14155550123",
    "countryCode": "US",
    "rate": {
      "ratePerUnit": "0.0075",
      "currency": "USD",
      "countryCode": "US"
    },
    "allIn": {
      "baseRatePerUnit": "0.0075",
      "currency": "USD",
      "surcharges": [
        {
          "code": "a2p_10dlc_registration",
          "label": "US A2P 10DLC brand + campaign registration",
          "unitPrice": 4,
          "appliesPer": "monthly_flat"
        },
        {
          "code": "premium_support",
          "label": "Premium support tier",
          "unitPrice": 99,
          "appliesPer": "monthly_flat"
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:00.000Z"
  }
}

2. Verify against your effective rate sheet

GET /api/v1/pricing/effective-rates is the tenant-facing read the what-if and estimate checks reconcile against: the global platform card collapsed with any per-org overrides down to the single row the billing resolver would charge per (channel, sub-type, country, direction) lane. Each row shows the bare base rate and the effective per-unit price in cents after overrides (and, for SMS, the platform default markup) are layered on — so the number you display cannot drift from the number the wallet debits. hasCustomRate is set only when your own org carried the override, never for the platform default.

curl -X GET "https://api.orbit.devotel.io/api/v1/pricing/effective-rates" \
  -H "X-API-Key: $ORBIT_API_KEY"

const sheet = await orbit.request("GET", "/api/v1/pricing/effective-rates");
// sheet.data — one row per billable lane

200

{
  "data": [
    {
      "channel": "sms",
      "subType": null,
      "countryCode": "US",
      "direction": "mt",
      "currency": "USD",
      "baseRatePerUnit": 0.0075,
      "effectivePerUnitCents": 0.825,
      "provider": "devotel",
      "hasCustomRate": false
    }
  ],
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:02.000Z"
  }
}

3. Replay traffic against a candidate rate card (the what-if)

POST /api/v1/pricing/whatif-simulate is the call you run before committing volume: it replays a window of your own observed traffic (one entry per billable lane, in usage) against a candidate rate card (candidateRates) and projects the cost side-by-side with what the traffic was actually billed. Traffic is held fixed; only the rate card is swapped — that is the what-if. It is read-only: nothing is written, nothing is sent, and an INSUFFICIENT_BALANCE at send time later means the top-up reminder was never a reason to skip this preview. Both arrays fill a real body — a bare {} returns 422.

curl -X POST "https://api.orbit.devotel.io/api/v1/pricing/whatif-simulate" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "usage": [
    { "channel": "sms", "countryCode": "US", "direction": "mt", "units": 12000, "currentBilledUsd": 96.40 },
    { "channel": "sms", "countryCode": "GB", "direction": "mt", "units": 4100, "currentBilledUsd": 58.10 }
  ],
  "candidateRates": [
    { "channel": "sms", "countryCode": "US", "direction": "mt", "ratePerUnit": 0.0075 },
    { "channel": "sms", "countryCode": "GB", "direction": "mt", "ratePerUnit": 0.012 },
    { "channel": "sms", "countryCode": "*", "direction": "mt", "ratePerUnit": 0.015 }
  ]
}'

const whatIf = await orbit.request("POST", "/api/v1/pricing/whatif-simulate", {
  usage: [
    { channel: "sms", countryCode: "US", direction: "mt", units: 12000, currentBilledUsd: 96.4 },
    { channel: "sms", countryCode: "GB", direction: "mt", units: 4100, currentBilledUsd: 58.1 },
  ],
  candidateRates: [
    { channel: "sms", countryCode: "US", direction: "mt", ratePerUnit: 0.0075 },
    { channel: "sms", countryCode: "GB", direction: "mt", ratePerUnit: 0.012 },
    { channel: "sms", countryCode: "*", direction: "mt", ratePerUnit: 0.015 },
  ],
});
// whatIf.data.totalDeltaUsd — negative = the candidate card is cheaper

200

{
  "data": {
    "lanes": [
      {
        "channel": "sms",
        "countryCode": "US",
        "direction": "mt",
        "subType": null,
        "units": 12000,
        "matchedRatePerUnit": 0.0075,
        "matchedCountryCode": "US",
        "projectedUsd": 90,
        "currentBilledUsd": 96.4,
        "deltaUsd": -6.4,
        "unmatched": false
      },
      {
        "channel": "sms",
        "countryCode": "GB",
        "direction": "mt",
        "subType": null,
        "units": 4100,
        "matchedRatePerUnit": 0.012,
        "matchedCountryCode": "GB",
        "projectedUsd": 49.2,
        "currentBilledUsd": 58.1,
        "deltaUsd": -8.9,
        "unmatched": false
      }
    ],
    "totalUnits": 16100,
    "totalProjectedUsd": 139.2,
    "totalCurrentBilledUsd": 154.5,
    "totalDeltaUsd": -15.3,
    "deltaPct": -9.9,
    "matchedLaneCount": 2,
    "unmatchedLaneCount": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:04.000Z"
  }
}

A lane no candidate row covers comes back with "unmatched": true and "matchedRatePerUnit": null — read unmatchedLaneCount before you trust totalProjectedUsd; a candidate card with coverage gaps under-projects.

4. Read the current rate card (admin)

GET /api/v1/pricing/rates is the super-admin read of the full platform rate card — every lane, global defaults and per-org rows alike, ordered by channel then country. Use it before you edit or retire a lane; the list is capped at 5,000 rows.

curl -X GET "https://api.orbit.devotel.io/api/v1/pricing/rates" \
  -H "X-API-Key: $ORBIT_ADMIN_KEY"

const card = await orbit.request("GET", "/api/v1/pricing/rates");

200

{
  "data": [
    {
      "id": "rate_01HZY8EXAMPLE",
      "organizationId": null,
      "channel": "sms",
      "subType": null,
      "countryCode": "US",
      "direction": "mt",
      "ratePerUnit": "0.0075",
      "currency": "USD",
      "provider": "devotel",
      "effectiveFrom": "2026-01-01T00:00:00.000Z",
      "effectiveTo": null,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:06.000Z"
  }
}

Each row carries exactly the fields shown above — identity, lane, per-unit price and currency, provider, scope, and effective window. Internal costing and provenance fields (costAmount, costCurrency, markupBps, source, sourceRef, createdBy) are not part of this list response; bill off the per-lane rate and effective window, and use the admin rate detail read when you need the full row.

5. Audit what a rate change did to a tenant’s bill

GET /api/v1/pricing/changelog answers “when did my pricing change, and what changed”. A super-admin sees the raw internal audit rows (actor, reason, before/after snapshots) and may filter by organizationId; a tenant API key gets the sanitized projection — which surface changed (rate_card or org_override), the action, whether it was a global rate-card change or org-scoped, and the timestamp — with the internal fields stripped, and scope pinned to the caller’s own org plus global changes. A tenant-supplied organizationId is ignored (no cross-tenant read). Cap with limit (default 100, max 500).

curl -X GET "https://api.orbit.devotel.io/api/v1/pricing/changelog?limit=50" \
  -H "X-API-Key: $ORBIT_API_KEY"

const changes = await orbit.request(
  "GET",
  "/api/v1/pricing/changelog?limit=50",
);

Tenant view (sanitized projection):

200

{
  "data": [
    {
      "id": "chg_01HZY8EXAMPLE",
      "resource": "org_override",
      "action": "update",
      "scope": "organization",
      "organizationId": "org_01HZY8ORG",
      "changedAt": "2026-09-08T15:42:11.000Z"
    },
    {
      "id": "chg_01HZY8EXAMP2",
      "resource": "rate_card",
      "action": "create",
      "scope": "global",
      "organizationId": null,
      "changedAt": "2026-09-01T09:00:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:08.000Z"
  }
}

Super-admins get the raw rows back instead, with the operator changedBy, a free-text reason, and the full beforeState / afterState snapshots — shape preserved verbatim, internal fields included. Pair the tenant view with /pricing/effective-rates to explain a line on a bill; pair the super-admin view with /pricing/overrides?organizationId=... to scope the audit to one tenant.

6. Operator-level SMS rate card with scope filters

GET /api/v1/pricing/mccmnc-rates is the customer-facing SMS rate card at mobile-operator (MCCMNC) granularity, with your organization’s markup already applied. Filter with search (operator name, country, or MCCMNC code) and country, and page with cursor / limit. A row with no published cost returns "your_rate": null — the “Contact sales” row — and pricing_source attributes each row to the same rule the send-path resolver bills under (override / org_markup / default_markup), so the preview cannot quote a price the wallet would not charge.

curl -X GET "https://api.orbit.devotel.io/api/v1/pricing/mccmnc-rates?search=Cosmote&limit=50" \
  -H "X-API-Key: $ORBIT_API_KEY"

const operators = await orbit.request(
  "GET",
  "/api/v1/pricing/mccmnc-rates?search=Cosmote&limit=50",
);

200

{
  "data": [
    {
      "mccmnc": "20201",
      "operator_name": "Cosmote",
      "country": "GR",
      "your_rate": 0.0462,
      "currency": "USD",
      "pricing_source": "default_markup"
    }
  ],
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:10.000Z",
    "pagination": {
      "cursor": "20201",
      "has_more": false
    }
  }
}

The same super-admin scope filters the picker and override surfaces use — /pricing/organizations (org rows with a hasCustomRates flag, all=true for one round trip) and /pricing/overrides?organizationId=org_... — let a team admin compare a tenant’s negotiated rates against the platform card before answering a dispute.

7. Public price list (no key needed)

GET /api/v1/public/pricing publishes the platform pay-as-you-go price list with the pricing-model manifest — one tier, no contact-sales gate, no forced migrations. It is unauthenticated and IP rate-limited, so a prospect can verify pricing before signing up. Pass ?country=US for the published country-specific list; omit it for the baseline.

curl -X GET "https://api.orbit.devotel.io/api/v1/public/pricing?country=US"

const published = await orbit.request(
  "GET",
  "/api/v1/public/pricing?country=US",
);

200

{
  "data": {
    "model": {
      "type": "pay_as_you_go",
      "singleTier": true,
      "planTiers": [],
      "contactSalesGated": false,
      "forcedMigrations": false,
      "currency": "USD",
      "note": "Single transparent pay-as-you-go model for every account — no plan tiers, no contact-sales gate, and no forced pricing-model migrations. You only pay published per-unit rates for what you send."
    },
    "country": "US",
    "channels": [
      {
        "channel": "sms",
        "unit": "per_segment",
        "ratePerUnit": 0.0165,
        "currency": "USD",
        "billed": true,
        "source": "platform-default"
      },
      {
        "channel": "voice",
        "unit": "per_minute",
        "ratePerUnit": 0.014,
        "currency": "USD",
        "billed": true,
        "source": "platform-default"
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:12.000Z"
  }
}

SMS is metered per segment (per_segment), not per message: a GSM-7 body splits every 160 characters and a UCS-2 (unicode) body every 70, so a long send costs N× the per-segment rate. Voice bills per minute, fax per page. Bring-your-own-credential channels (WhatsApp, Instagram, Messenger, push, Apple Messages, LINE) are listed with "billed": false at $0 — the platform only charges for what it terminates itself.

Rate-card data is scoped to your own organization: tenant keys can read only their own effective rates and overrides, never another tenant’s negotiated pricing. Rates are resolved in the currency of the lane they price (USD by default). This is a tenant-owned control — the platform enforces the scope, you choose how far the card travels.

8. Preview per-country messaging rates by channel

GET /api/v1/pricing/messaging answers “what does it cost to message this country, channel by channel” in one call: SMS, MMS, WhatsApp, RCS, and Viber per-unit rates for the ISO alpha-2 country you pass, with your organization’s effective price already collapsed in (effectiveRatePerUnit). A channel with no country-specific row falls back to the published platform default. hasCustomRate flips true only when a per-org override applied. The country query is a price-lookup key — it never routes traffic.

curl -X GET "https://api.orbit.devotel.io/api/v1/pricing/messaging?country=US" \
  -H "X-API-Key: $ORBIT_API_KEY"

const messaging = await orbit.request(
  "GET",
  "/api/v1/pricing/messaging?country=US",
);
// messaging.data.channels — one row per channel

messaging = client.request(
    "GET",
    "/api/v1/pricing/messaging",
    params={"country": "US"},
)

200

{
  "data": {
    "country": "US",
    "channels": [
      {
        "channel": "sms",
        "countryCode": "US",
        "direction": "mt",
        "baseRatePerUnit": 0.0165,
        "effectiveRatePerUnit": 0.0181,
        "currency": "USD",
        "unit": "per_message",
        "hasCustomRate": false,
        "provider": "devotel"
      },
      {
        "channel": "mms",
        "countryCode": "US",
        "direction": "mt",
        "baseRatePerUnit": 0.02,
        "effectiveRatePerUnit": 0.02,
        "currency": "USD",
        "unit": "per_message",
        "hasCustomRate": false,
        "provider": null
      },
      {
        "channel": "whatsapp",
        "countryCode": "US",
        "direction": "mt",
        "baseRatePerUnit": 0,
        "effectiveRatePerUnit": 0,
        "currency": "USD",
        "unit": "per_message",
        "hasCustomRate": false,
        "provider": null
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:14.000Z"
  }
}

Bring-your-own-credential channels (WhatsApp, Meta’s other surfaces, LINE, Telegram, push) price at $0 — the platform bills only what it terminates, and the per-channel fallback default keeps the row list complete either way.

9. Preview voice rates for a country

GET /api/v1/pricing/voice is the per-minute counterpart: inbound (mo) and outbound (mt) voice rates for one country, split into two arrays the same way Twilio’s Pricing API splits them. Per-minute billing, USD, with the same override-collapse the message preview applies.

curl -X GET "https://api.orbit.devotel.io/api/v1/pricing/voice?country=US" \
  -H "X-API-Key: $ORBIT_API_KEY"

const voice = await orbit.request(
  "GET",
  "/api/v1/pricing/voice?country=US",
);
// voice.data.outbound / voice.data.inbound

voice = client.request("GET", "/api/v1/pricing/voice", params={"country": "US"})

200

{
  "data": {
    "country": "US",
    "outbound": [
      {
        "channel": "voice",
        "countryCode": "US",
        "direction": "mt",
        "baseRatePerUnit": 0.012,
        "effectiveRatePerUnit": 0.012,
        "currency": "USD",
        "unit": "per_minute",
        "hasCustomRate": false,
        "provider": "devotel"
      }
    ],
    "inbound": [
      {
        "channel": "voice",
        "countryCode": "US",
        "direction": "mo",
        "baseRatePerUnit": 0.0085,
        "effectiveRatePerUnit": 0.0085,
        "currency": "USD",
        "unit": "per_minute",
        "hasCustomRate": false,
        "provider": "devotel"
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:16.000Z"
  }
}

The outbound side is the customer-facing per-minute price — routing is a separate concern that stays internal.

10. Preview phone-number rental prices

GET /api/v1/pricing/phone-numbers prices DID inventory before you buy: the monthly rental of each purchasable number type in one country, with the cheapest available cost and how many are in stock. Only unassigned, purchasable inventory is counted, so tenants can never enumerate which DIDs already belong to someone else. A country with no purchasable inventory returns an empty phoneNumbers list, not an error.

curl -X GET "https://api.orbit.devotel.io/api/v1/pricing/phone-numbers?country=US" \
  -H "X-API-Key: $ORBIT_API_KEY"

const numbers = await orbit.request(
  "GET",
  "/api/v1/pricing/phone-numbers?country=US",
);

numbers = client.request(
    "GET",
    "/api/v1/pricing/phone-numbers",
    params={"country": "US"},
)

200

{
  "data": {
    "country": "US",
    "phoneNumbers": [
      {
        "numberType": "local",
        "monthlyCost": "1.00",
        "currency": "USD",
        "available": 412,
        "total": 412
      },
      {
        "numberType": "tollfree",
        "monthlyCost": "2.00",
        "currency": "USD",
        "available": 96,
        "total": 96
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:18.000Z"
  }
}

11. Read the RTC-PaaS rate card

GET /api/v1/pricing/rtc-rate-card publishes the whole video/audio room pricing sheet in one response so a simulator or pricing UI can render without a round trip: the per-participant-minute price for each resolution tier, the add-ons bundled into that rate, and the three add-on fees billed on top (extra RTMP destinations, recording storage, dedicated SFU). Pair it with POST /pricing/rtc-simulate (§12) to forecast a workload from the same numbers.

curl -X GET "https://api.orbit.devotel.io/api/v1/pricing/rtc-rate-card" \
  -H "X-API-Key: $ORBIT_API_KEY"

const rtc = await orbit.request("GET", "/api/v1/pricing/rtc-rate-card");

rtc = client.request("GET", "/api/v1/pricing/rtc-rate-card")

200

{
  "data": {
    "currency": "USD",
    "tierRatesPerParticipantMinute": {
      "audio_only": 0.0015,
      "sd": 0.0035,
      "hd": 0.0055,
      "fhd": 0.0095
    },
    "bundledAddOns": [
      "signaling",
      "recording (composite + per-track)",
      "live captions / STT",
      "1 RTMP destination",
      "SFU → participant bandwidth"
    ],
    "rtmpExtraDestinationPerMinute": 0.004,
    "recordingStoragePerGbMonth": 0.02,
    "dedicatedSfuMonthlyFee": 350
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:20.000Z"
  }
}

Every tier bills one blended per-participant-minute rate; add-ons you see outside bundledAddOns are the optional extras below.

12. Forecast an RTC workload

POST /api/v1/pricing/rtc-simulate turns a workload spec into a line-item forecast that mirrors the eventual invoice: resolution tier, average participants, minutesPerRoom, roomsPerMonth, and the optional extras. The same math runs in the dashboard simulator, so the forecast cannot drift. Volumes here are illustrative — the endpoint never aggregates your total R&D spend.

curl -X POST "https://api.orbit.devotel.io/api/v1/pricing/rtc-simulate" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tier": "hd",
  "participants": 8,
  "minutesPerRoom": 45,
  "roomsPerMonth": 200,
  "extraRtmpDestinations": 1,
  "recordingStorageGb": 40
}'

const forecast = await orbit.request("POST", "/api/v1/pricing/rtc-simulate", {
  tier: "hd",
  participants: 8,
  minutesPerRoom: 45,
  roomsPerMonth: 200,
  extraRtmpDestinations: 1,
  recordingStorageGb: 40,
});
// forecast.data.totalMonthlyUsd

forecast = client.request(
    "POST",
    "/api/v1/pricing/rtc-simulate",
    json={
        "tier": "hd",
        "participants": 8,
        "minutesPerRoom": 45,
        "roomsPerMonth": 200,
        "extraRtmpDestinations": 1,
        "recordingStorageGb": 40,
    },
)

200

{
  "data": {
    "tier": "hd",
    "bundledAddOns": [
      "signaling",
      "recording (composite + per-track)",
      "live captions / STT",
      "1 RTMP destination",
      "SFU → participant bandwidth"
    ],
    "participantMinutes": 72000,
    "lineItems": [
      {
        "label": "RTC HD (bundled)",
        "unitDescription": "participant-minute",
        "units": 72000,
        "unitPriceUsd": 0.0055,
        "subtotalUsd": 396
      },
      {
        "label": "Extra RTMP fan-out (1 destination)",
        "unitDescription": "destination-minute",
        "units": 9000,
        "unitPriceUsd": 0.004,
        "subtotalUsd": 36
      },
      {
        "label": "Recording storage",
        "unitDescription": "GB-month",
        "units": 40,
        "unitPriceUsd": 0.02,
        "subtotalUsd": 0.8
      }
    ],
    "totalMonthlyUsd": 432.8,
    "blendedRatePerParticipantMinuteUsd": 0.006
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:22.000Z"
  }
}

Read blendedRatePerParticipantMinuteUsd when you want the single defensible blended rate for a budget line — it folds the extras back into a per-minute number.

13. Pick an organization for the rate-card editor (admin)

GET /api/v1/pricing/organizations fills the super-admin rate-card editor’s org picker: one row per organization with a hasCustomRates flag that flips when the org has at least one per-org override, so the operator can jump straight to tenants with custom pricing. Keyset-paginated by (name, id); pass all=true to load the whole roster in one round trip instead of cursor-walking.

curl -X GET "https://api.orbit.devotel.io/api/v1/pricing/organizations?all=true" \
  -H "X-API-Key: $ORBIT_ADMIN_KEY"

const orgs = await orbit.request(
  "GET",
  "/api/v1/pricing/organizations?all=true",
);

orgs = client.request(
    "GET",
    "/api/v1/pricing/organizations",
    params={"all": "true"},
)

200

{
  "data": [
    {
      "id": "org_01HZY8EXAMP",
      "name": "Fulcrum Freight LLC",
      "slug": "fulcrum-freight",
      "hasCustomRates": true
    },
    {
      "id": "org_01HZY8EXAM2",
      "name": "Nordwind Logistics",
      "slug": "nordwind-logistics",
      "hasCustomRates": false
    }
  ],
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:24.000Z",
    "pagination": {
      "cursor": null,
      "has_more": false
    }
  }
}

14. Review per-org override lanes (admin)

GET /api/v1/pricing/overrides lists the negotiated per-org override rows — optionally scoped with organizationId, otherwise the active overrides across every tenant. Use it to answer “which lanes does this tenant price custom on” before a support dispute. Super-admin only; capped at 5,000 rows.

curl -X GET "https://api.orbit.devotel.io/api/v1/pricing/overrides?organizationId=org_01HZY8EXAMP" \
  -H "X-API-Key: $ORBIT_ADMIN_KEY"

const overrides = await orbit.request(
  "GET",
  "/api/v1/pricing/overrides?organizationId=org_01HZY8EXAMP",
);

overrides = client.request(
    "GET",
    "/api/v1/pricing/overrides",
    params={"organizationId": "org_01HZY8EXAMP"},
)

200

{
  "data": [
    {
      "id": "opr_01HZY8EXAMP",
      "organizationId": "org_01HZY8EXAMP",
      "channel": "sms",
      "subType": null,
      "countryCode": "US",
      "direction": "mt",
      "absolutePriceCents": "1.45",
      "markupBps": null,
      "markupPercentage": null,
      "markupFixedCents": null,
      "effectiveFrom": "2026-07-01T00:00:00.000Z",
      "effectiveTo": null,
      "createdAt": "2026-06-28T11:12:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-09-10T12:00:26.000Z"
  }
}

An override priced by absolutePriceCents (like this one) replaces the base rate outright; markupBps / markupPercentage / markupFixedCents layer on top of the base instead — one mechanism per row.

15. Errors worth branching on

The envelope mechanics — error.code / message / status / details, retry order, retriable-vs-terminal — live once in the error-handling guide. Here is what the branch decision on THIS page comes down to.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid what-if simulator input",
    "status": 422,
    "details": { "issues": [{ "field": "usage", "message": "Required" }] }
  },
  "meta": { "request_id": "req_01HZY8EXAMPLE", "timestamp": "2026-09-10T12:00:14.000Z" }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Super admin access required",
    "status": 403
  },
  "meta": { "request_id": "req_01HZY8EXAMPLE", "timestamp": "2026-09-10T12:00:16.000Z" }
}

Class	Meaning	Branch response
422 `VALIDATION_ERROR`	A bare `{}` body on either simulator, a missing/malformed `country`, or `channel`/`to` omitted on estimate. Typed out-of-range input the API cannot price.	Fix then resend. The `details.issues` array names the field — correct the body/params, then re-issue. Never retry a 422 blind.
403 `FORBIDDEN`	A tenant key presented against `/pricing/rates`, `/pricing/organizations`, or `/pricing/overrides` — the super-admin-only reads.	Surface. These are admin surfaces; the tenant-facing equivalents (`/pricing/effective-rates`, `/pricing/mccmnc-rates`) return 200. Do not retry against the admin path until the key is a super-admin key.
429 `RATE_LIMITED`	The auth-write bucket pricing reads draw from is exhausted. Reads are cheap; the bucket reset is fast.	Retry after `error.details.retry_after`. Public pricing draws from the public-IP bucket; estimate + simulators draw from the auth bucket.
401 `INVALID_API_KEY`	Missing or revoked key. Present on every `/pricing/*` route except `/public/pricing`.	Fix, then re-key. A tenant-scoped read with no valid key is a hard terminal — re-issue credentials, do not retry.
402 `INSUFFICIENT_BALANCE` (interplay)	A send that follows an estimate can still hit this at the wallet; the estimate endpoint itself never charges.	Top up, then resend the send. The estimate response is a preview — a later `INSUFFICIENT_BALANCE` on the real send means the wallet ran dry between estimate and send, not that the estimate lied.

Treat 422 and 403 as terminal, not retriable — a corrected request fixes the first; the second needs a super-admin key or a switch to the tenant-facing read. 429 and 401 are retry-once-after-fix and re-key-then-retry respectively. The pricing reads draw from the same RATE_LIMIT_AUTH_WRITE bucket as the other authenticated reads, and the public list has its own IP bucket — the envelope’s error.details.retry_after says how long. These samples compound; the auto-generated per-operation entries below always carry the full parameter table even where a sample here already covers the op. Further reading: the billing cost calculator guide sizes a first top-up from these rates, the what-if pricing simulator guide walks the dashboard surface, and the billing what-if preview + spend/burn recipe (API recipes §22) chains the preview, burn-rate, and spend-series calls.

API Reference

All Endpoints

Estimate a send end-to-end

Step 1 — Look up a destination country and channel

Step 2 — Cost a planned campaign

Step 3 — What-if a single message

Step 4 — Currency and rounding rules

Worked pricing samples

1. Estimate one destination before you send

2. Verify against your effective rate sheet

3. Replay traffic against a candidate rate card (the what-if)

4. Read the current rate card (admin)

5. Audit what a rate change did to a tenant’s bill

6. Operator-level SMS rate card with scope filters

7. Public price list (no key needed)

8. Preview per-country messaging rates by channel

9. Preview voice rates for a country

10. Preview phone-number rental prices

11. Read the RTC-PaaS rate card

12. Forecast an RTC workload

13. Pick an organization for the rate-card editor (admin)

14. Review per-org override lanes (admin)

15. Errors worth branching on

​Estimate a send end-to-end

​Step 1 — Look up a destination country and channel

​Step 2 — Cost a planned campaign

​Step 3 — What-if a single message

​Step 4 — Currency and rounding rules

​Worked pricing samples

​1. Estimate one destination before you send

​2. Verify against your effective rate sheet

​3. Replay traffic against a candidate rate card (the what-if)

​4. Read the current rate card (admin)

​5. Audit what a rate change did to a tenant’s bill

​6. Operator-level SMS rate card with scope filters

​7. Public price list (no key needed)

​8. Preview per-country messaging rates by channel

​9. Preview voice rates for a country

​10. Preview phone-number rental prices

​11. Read the RTC-PaaS rate card

​12. Forecast an RTC workload

​13. Pick an organization for the rate-card editor (admin)

​14. Review per-org override lanes (admin)

​15. Errors worth branching on

Estimate a send end-to-end

Step 1 — Look up a destination country and channel

Step 2 — Cost a planned campaign

Step 3 — What-if a single message

Step 4 — Currency and rounding rules

Worked pricing samples

1. Estimate one destination before you send

2. Verify against your effective rate sheet

3. Replay traffic against a candidate rate card (the what-if)

4. Read the current rate card (admin)

5. Audit what a rate change did to a tenant’s bill

6. Operator-level SMS rate card with scope filters

7. Public price list (no key needed)

8. Preview per-country messaging rates by channel

9. Preview voice rates for a country

10. Preview phone-number rental prices

11. Read the RTC-PaaS rate card

12. Forecast an RTC workload

13. Pick an organization for the rate-card editor (admin)

14. Review per-org override lanes (admin)

15. Errors worth branching on