Skip to main content

​
Reseller margin and the tax pipeline

Platforms reselling Devotel Orbit — agencies, MSPs, vertical SaaS — price their end customers’ usage on top of the cost Orbit computes. Two different levers do that, and this page exists to keep them straight: a rate markup, which prices usage against a rate card, and a reseller margin, which marks up the resulting bill. The Usage Metering API carries the margin lever; the pricing and rate resolution page carries the markup lever. Read this page before you quote a margin percentage to your own customers, or before you reconcile the rollup, the margin preview, and the tax line against each other.

​
What a reseller margin is

A reseller margin is a percentage (0–100) you pass per rating request, applied to each subaccount’s rated amount. The rated amount is what the meter definition produced: the usage events you POSTed, counted in the meter’s unit, with includedQuantity bundled at no charge and the overflow priced against graduated overageTiers. The margin multiplies that per-subaccount total, never the individual usage event. Setting itemize_fees: true on the invoice block splits every line and the totals into the pass-through cost (base_* fields) and your margin — the document can show your customer either the blended price or the cost-plus-margin breakdown. Omitting the margin, or passing 0, bills at cost.

​
Margin versus markup — the distinction that drives the design

A rate markup resolves the price of usage: operator cost × your organization’s markup, resolved per send, following the precedence on pricing and rate resolution. A reseller margin resolves the price of the bill: rated amount × your percentage, resolved per subaccount, after the meter has run across the whole batch. They compose cleanly because they operate on different stages. Live Orbit traffic is priced by the markup side; when you re-rate that usage for your own end customers through the Usage Metering API, the margin side applies to the totals the meter computed. Never apply a margin to an unresolved rate and never apply it to individual events — both produce numbers the ledger descriptors cannot reproduce.

​
Margin before tax — the ordering rule

The margin applies to the rated amount before the tax line computes. Tax is a percentage of the marked-up subtotal: if your margin added 20% to a 33.60ratedamount,an833.60 rated amount, an 8% tax computes on 40.32, not on $33.60. The invoice fields make the ordering auditable: subtotal_minor is the marked-up amount, and tax_minor is derived from it. The exemption branch sits on that same ordering. Only an approved certificate whose jurisdiction matches tax.jurisdiction (or a blanket certificate with no jurisdiction) and whose validity window covers the rating period suppresses the tax line. A pending, rejected, or expired status — or an approved certificate whose validity window has lapsed — taxes the invoice as normal. The invoice echoes both the status you passed (tax_exemption_status) and whether suppression actually happened (tax_exemption_applied), so an auditor can tell an untaxed invoice from a mistakenly untaxed one. Resolving the certificate is a control your billing team owns: you pass the resolved certificate into the request, and the response applies it. Orbit does not store exemption certificates for your end customers.

​
Ledger descriptors, not wallet movements

The margin lands on billing documents and ledger write descriptors, not on any wallet. When you rate a batch, the response’s billing block carries ledger_entries — the per-subaccount debit descriptors (amount, base amount, reference) you would commit in your own billing flow — and, when you supply the invoice block, the branded HTML document you hand your end customer. Nothing moves: no wallet is debited, no invoice is persisted, no payout ledger is written. That separation is deliberate. Your end customers’ ledgers live in your system, and Orbit’s own wallet is never a party to your resale. The preview endpoints return the exact descriptors you would write, so the commit step in your flow is a replay of a previewed number, not a fresh computation.

​
Three surfaces, one story

Three independent surfaces compute margin-related numbers, and they must agree:
  1. The rollup (POST /api/v1/usage/meters/rollup) — the rated batch with your margin applied per subaccount.
  2. The margin roll-up preview — the read-only projection of what the current period would close at, covered with the other preview endpoints on the pricing-preview pipeline.
  3. Live rating — Orbit’s own rated usage the way you pass it into the meter.
Treat a disagreement between the preview and the rollup you commit as a data bug in your own flow (a missing event, a shifted rating window), not as a tolerance. Because none of these surfaces writes anything, you can re-run them freely to reconcile before you commit.

​
Boundaries — what this page does not cover