Skip to main content

​
Committed-use drawdown

Enterprise buyers typically sign a monthly spend commitment in exchange for a discounted per-unit rate: you promise to spend at least X per billing period, and in return your unit prices drop. Your metered usage then draws down against that commitment over the period, and at period end the gap is trued up:
  • If your consumption falls short of the commit, you still owe the floor — the unmet remainder is the minimum-commit true-up charge (“use it or pay it”).
  • If your consumption exceeds the commit, the commitment is fully drawn down and the excess is billed on top as overage.
This is a different billing posture from Orbit’s prepaid wallet. The wallet is authorize-before-use: every send pre-flights the balance and debits in real time against funds you already deposited (see Wallets, credits, and charges). A committed-use contract does not replace the wallet — usage still debits the wallet as it happens — it adds a period-level contract meter on top of the same ledger. The meter answers two finance questions the wallet balance cannot: “how much of my commit have I consumed?” and “am I trending toward a shortfall true-up or an overage?”

​
Where the commitment is configured

The commitment itself is a negotiated contract term, and it lives ops-side — not as a tenant setting. Platform ops stores it on your organization at settings.billing.committedUse, following the same posture as other contract-level billing terms (such as your self-credit ceiling): the API offers no tenant-writable PATCH for it. You cannot set, raise, or lower your own commitment from the dashboard or the API — changes go through your account contact, same as renegotiating the contract. The commitment object looks like this:
Only monthlyCommitCents (the committed spend per billing period, in wallet cents) is required, and it must be a positive whole number. Everything else is optional: discountPercent (0–100) is the negotiated rate discount, informational for the meter; currency is a display hint; termStart / termEnd are the ISO dates of the contract term. A malformed or missing object is treated as no commitment, defensively — a typo in the ops configuration never fabricates a phantom commit.

​
Reading the meter

The meter is one read-only endpoint:
It returns the commitment, the current billing period bounds, and — when a commitment exists — a full drawdown block computed from your existing usage ledger:
When no commitment is configured, the endpoint returns an explicit null envelope — commitment: null — with the period bounds and your period-to-date spend for context:
The dashboard’s commitment panel keys off that shape: commitment: null means self-hide — an org without a commit never sees an empty or broken-looking meter, and you never have to distinguish “no contract” from “a zeroed contract.” Treat commitment: null the same way in your own integration: it is the expected steady state for orgs without a committed-use contract, not an error. A moved organization (missing or soft-deleted) is the one case that answers an error instead — a consistent 404 like the other org-scoped billing reads.

​
Drawdown math

The projection is deliberately transparent — a linear run-rate, not an ML forecast, the same no-magic approach the cost-forecast surfaces elsewhere in the dashboard use:
From that projection, the end-of-period true-up falls out directly:
  • projected_shortfall_cents = max(0, committed_cents − projected_spend_cents) — the minimum-commit true-up you would owe if the current pace held.
  • projected_overage_cents = max(0, projected_spend_cents − committed_cents) — the excess you would bill on top of the commit.
The shortfall_cents / overage_cents pair answers the same question as of right now (period ending today), while the projected_* pair extrapolates to period end. The status field condenses the comparison into the three states the meter colour-codes:
  • exhausted — consumption has already met or exceeded the commit.
  • on_track — the run-rate projection reaches the commit by period end.
  • under_pace — the projection falls short; a true-up is likely at the current pace.
Inputs are defensively clamped — consumption is floored at zero, the period is never shorter than one day, and days-elapsed is clamped into the period — so a clock skew or a request at the period boundary can’t divide by zero or project a negative run-rate.

​
Behavior guarantees

Two guarantees make the meter safe to poll from an always-on dashboard:
  1. It moves no money. The endpoint is a pure read against the metered spend your billing paths already record. It issues no charges, creates no ledger rows, and never triggers the true-up itself — minimum-commit true-ups are settled through your contract invoicing, not this meter.
  2. It degrades to hidden, never to an error storm. If a transient infrastructure failure hits before the handler can even run (for example while resolving your tenant), the billing routes degrade the would-be 503 into the same commitment: null envelope the “no commitment” case returns. A dashboard poll during an infrastructure blip renders the panel-hidden state and recovers on the next poll, instead of surfacing a hard error on an always-on widget. Your integration should key on commitment: null (poll hidden), not on the period fields.

​
API contract

Response when a commitment exists — field reference:

​
What this is not

  • Not a payment method. A commitment does not fund usage; your wallet still needs balance for sends to pre-flight. Auto-top-up and balance alerts work exactly as before.
  • Not a spend cap. Reaching 100% drawdown never blocks sending — the meter reports, it does not gate. Tenant-owned caps live in Spend caps.
  • Not self-service. Setting or changing the commitment is an ops action tied to your contract; there is intentionally no API to write it.

​
See also