​

Rate cards

​

What a rate card is

• Lane cells — candidate per-lane rates captured from the what-if pricing preview (POST /billing/whatif-pricing/preview), kept verbatim. A lane is a channel/country/direction pair, such as “WhatsApp to Nigeria.”
• Deck cells — channel[, destination] → margin_pct markup cells, the same shape an inline rate deck uses.

​

Dashboard walkthrough

​

Build the library

1. Open Settings → Subaccounts, then pick any child subaccount and open its Pricing tab. The top card is Rate cards — your reusable library.
2. Click New rate card. Give it a name (for example, “West Africa Gold”). The dashboard slugifies the name into a card id like rc_west_africa_gold.
3. Add markup cells: a channel (sms, whatsapp, voice, …), an optional destination (NG, GB, US, …), and a margin percent (0–100). Leave destination blank to cover every destination on that channel.
4. Click Save card. The card is appended to your library and the table shows its id, name, and cell counts.
5. Delete a card from the library with the row’s trash icon. Subaccounts already assigned to that card then show a Stale link badge on their Pricing tab and fall back to their flat reseller margin until you re-assign a different card.

​

Assign a card to a subaccount

1. Find Assigned rate card.
2. Choose a saved card from the dropdown, or choose None — inline deck to price the child from its own inline rate deck (or the flat margin when no deck exists).
3. The assignment is stored immediately. From the next send onward, the child resolves against the selected card’s cells.

​

Rate-card lifecycle: create, version, persist, assign

​

Assignment

curl -X PUT https://api.orbit.devotel.io/api/v1/subaccounts/sub_abc123/assigned-rate-card \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{ "rate_card_id": "rc_whatsapp_west_africa" }'

​

Limits

• Library cap: a parent org can store at most 50 named rate cards.
• Per-card cell cap: each card can hold at most 200 total cells (lane_cells + deck_cells combined). That is the same cap as a subaccount’s inline rate deck.
• Inline-deck limits: when you assign a card with deck cells, those cells are resolved exactly like an inline deck, so the same rate-deck limits and matching rules that apply to PUT /api/v1/subaccounts/:id/rate-deck apply here. A card cell is a channel/destination/margin_pct tuple, the same shape as an inline deck entry.

​

Safe concurrent versioning of the full-set PUT

1. Admin A GETs the library.
2. Admin B GETs the same library.
3. Admin A adds a card and PUTs.
4. Admin B edits a different card and PUTs — Admin B’s payload does not contain Admin A’s new card, so Admin A’s card disappears.

• serialize edits within your team, or
• always start from a fresh GET immediately before the PUT, and retry if a recent change from another session is missing.

​

Validation error catalog

​

Migration path: flat margin → inline deck → assigned rate card

1. Flat margin only — set reseller_margin_pct on the subaccount. Every usage line prices at wholesale × (1 + reseller_margin_pct / 100). This is the simplest starting point.
2. Inline rate deck — add per-channel/destination markup cells with PUT /api/v1/subaccounts/:id/rate-deck. The deck overrides the flat margin for matching lanes; anything not covered still falls back to the flat margin.
3. Assigned rate card — build a named card in the parent’s library and assign it to the subaccount. The card’s deck cells are used in place of the inline deck. The inline deck stays stored on the child, but is ignored while an assigned card is active.

​

Precedence summary

1. Assigned rate card — if the child has assigned_rate_card_id pointing to a card that still exists in the parent’s library, the card’s deck cells supply the markup.
2. Inline rate deck — if no assigned card is active, the child’s own reseller_rate_deck cells supply the markup.
3. Flat reseller margin — if neither card nor deck covers the lane, the child’s reseller_margin_pct is used.

​

Impact and retroactive semantics

• Which children are affected: only direct children of the parent org that have the card assigned via assigned_rate_card_id. Sibling parent orgs cannot see or assign your cards.
• When the change takes effect: at the next send. Rate resolution reads the current card at send time, so there is no batch delay.
• Past usage: already-sent traffic is not re-rated. The usage statement for a past period reflects the card (or deck, or flat margin) that was active when the traffic was sent. If you need to model what a new card would have cost on historical traffic, use the what-if pricing simulator.
• Deleting a card: assigned children fall back to their inline deck or flat margin immediately. The assignment row shows a stale-link badge until you clear or replace it.

​

Example: WhatsApp card with a 5% margin

curl -X PUT https://api.orbit.devotel.io/api/v1/subaccounts/rate-cards \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cards": [
      {
        "id": "rc_whatsapp_west_africa",
        "name": "WhatsApp West Africa Q3",
        "deck_cells": [
          { "channel": "whatsapp", "destination": "NG", "margin_pct": 5 },
          { "channel": "whatsapp", "destination": "GH", "margin_pct": 5 }
        ]
      }
    ]
  }'

curl -X PUT https://api.orbit.devotel.io/api/v1/subaccounts/sub_acme/assigned-rate-card \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{ "rate_card_id": "rc_whatsapp_west_africa" }'

​

Worked example: a lane cell captured from what-if pricing

{
  "channel": "voice",
  "country_code": "NG",
  "direction": "mt",
  "sub_type": null,
  "rate_per_unit": 0.0450,
  "markup_bps": 800,
  "absolute_price_cents": null
}

curl -X PUT https://api.orbit.devotel.io/api/v1/subaccounts/rate-cards \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cards": [
      {
        "id": "rc_voice_west_africa_preview",
        "name": "Voice West Africa preview",
        "lane_cells": [
          {
            "channel": "voice",
            "country_code": "NG",
            "direction": "mt",
            "sub_type": null,
            "rate_per_unit": 0.0450,
            "markup_bps": 800,
            "absolute_price_cents": null
          }
        ]
      }
    ]
  }'

​

Related pages

• White-label subaccounts — provision, brand, and fund children; the flat margin and inline deck the rate card builds on.
• Pricing and rate resolution — the per-operator precedence the assigned card feeds into.
• What-if pricing simulator — back-test a candidate rate card against your own traffic before you assign it.
• Wallet currency conversion — how converted top-ups interact with the wallet a subaccount draws down.
• Per-channel connection mode: BYO vs platform default — the connection your subaccounts’ sends exit on, independent of how the rate card prices them.
• Subaccounts API — full endpoint schemas for the card library and assignment routes.