> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Committed-use drawdown: the enterprise monthly commit meter > What a committed-use contract is, where the ops-side commitment lives, how to read the drawdown meter (GET /billing/commitment), the run-rate projection behind its true-up figures, and why the meter degrades to a hidden panel instead of an error. # 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](/concepts/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: ```json theme={null} { "monthlyCommitCents": 500000, "discountPercent": 15, "currency": "USD", "termStart": "2026-01-01", "termEnd": "2026-12-31" } ``` 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: ``` GET /api/v1/billing/commitment ``` It returns the commitment, the current billing period bounds, and — when a commitment exists — a full drawdown block computed from your existing usage ledger: ```json theme={null} { "commitment": { "monthly_commit_cents": 500000, "discount_percent": 15, "currency": "USD", "term_start": "2026-01-01", "term_end": "2026-12-31" }, "period_start": "2026-09-01T00:00:00.000Z", "period_end": "2026-10-01T00:00:00.000Z", "drawdown": { "committed_cents": 500000, "consumed_cents": 236400, "remaining_cents": 263600, "drawdown_percent": 47.3, "overage_cents": 0, "shortfall_cents": 263600, "projected_spend_cents": 452210, "projected_overage_cents": 0, "projected_shortfall_cents": 47790, "days_elapsed": 16, "days_in_period": 30, "days_remaining": 14, "status": "under_pace" } } ``` 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: ```json theme={null} { "commitment": null, "period_start": "2026-09-01T00:00:00.000Z", "period_end": "2026-10-01T00:00:00.000Z", "current_spend_cents": 236400 } ``` 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: ``` projected_spend_cents = (consumed_cents / days_elapsed) × days_in_period ``` 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 ```bash theme={null} curl -s https://orbit.devotel.io/api/v1/billing/commitment \ -H "Authorization: Bearer $ORBIT_API_KEY" ``` Response when a commitment exists — field reference: | Field | Meaning | | ------------------------------------------------------------- | ------------------------------------------------- | | `commitment.monthly_commit_cents` | Committed spend per billing period (wallet cents) | | `commitment.discount_percent` | Negotiated rate discount (0–100), informational | | `commitment.currency` | Display currency hint | | `commitment.term_start` / `term_end` | Contract term dates (ISO) | | `period_start` / `period_end` | Current billing period bounds | | `drawdown.committed_cents` | The commitment floor for the period | | `drawdown.consumed_cents` | Period-to-date metered spend | | `drawdown.remaining_cents` | Commit still undrawn | | `drawdown.drawdown_percent` | Share of the commit consumed, 0–100 | | `drawdown.overage_cents` | Already-incurred excess over the commit | | `drawdown.shortfall_cents` | True-up owed if the period ended now | | `drawdown.projected_spend_cents` | Linear run-rate projection of end-of-period spend | | `drawdown.projected_overage_cents` | Projected excess at period end | | `drawdown.projected_shortfall_cents` | Projected true-up at period end | | `drawdown.days_elapsed` / `days_in_period` / `days_remaining` | Period pacing counters | | `drawdown.status` | `exhausted` / `on_track` / `under_pace` | ## 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](/billing/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 * [Billing and wallet overview](/concepts/billing-and-wallet) — the prepaid wallet this meter sits on top of. * [Wallets, credits, and charges](/concepts/wallets-credits-and-charges) — the ledger the drawdown reads from. * [Spend alerts and the velocity-anomaly model](/concepts/spend-anomaly-and-alert-model) — proactive spend protection that complements contract metering. * [Usage anomaly alerts](/billing/usage-anomaly-alerts) — threshold alerts you configure yourself. * [Cost-center chargeback](/guides/cost-center-chargeback) — attribute the same metered spend to internal cost centers.