> ## 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 discounts: decide, forecast, and enroll

> How a committed-use discount differs from volume tiers and pay-as-you-go, how to forecast your savings with the what-if pricing simulator before committing, how enrollment works, and how committed spend appears on your invoice.

# Committed-use discounts: decide, forecast, and enroll

A committed-use discount (CUD) trades a predictable monthly spend floor for a lower per-unit price: you commit to spending at least a fixed amount per billing period, and in return your unit prices drop for the whole term. This guide walks through deciding whether a commitment pays for itself on your traffic, forecasting the savings before you sign, enrolling, and reading the commitment back on your invoice and drawdown meter.

If you only ever want the meter reference (field-by-field response anatomy and the run-rate math), read [Committed-use drawdown](/concepts/committed-use-drawdown-model). This guide covers the decision and enrollment side.

## 1. CUD versus volume tiers versus pay-as-you-go

Orbit prices usage three ways, and they differ in where the discount comes from:

| Model | Where the discount comes from | Who it suits |
| - | - | - |
| **Pay-as-you-go** | Nowhere. Every unit bills at the live rate card; spend flexes with traffic. | Variable or early-stage traffic. |
| **Volume tiers** | Crossing a monthly volume breakpoint. The discount is earned retroactively each month and rolls back silently if traffic slips under the breakpoint. | Traffic that clears a breakpoint reliably but varies month to month. |
| **Committed-use discount** | Committing monthly spend up front, for a contract term. The discount applies because you committed, not because you crossed any threshold. | Steady traffic you can forecast, and a finance team that prefers a known floor. |

The distinction that matters when deciding:

* A volume tier rewards you for a volume level you **reach**; a CUD rewards you for a spend level you **promise**. A quiet month on a CUD still bills the commit (see [Undershoot and overshoot](#7-renewal-cancellation-and-what-happens-when-usage-misses-the-commit)); a quiet month on a volume tier just prices that month at the lower tier.
* A CUD discount is fixed for the term and applies to your rates regardless of breakpoints, so it stacks predictably into your unit economics; volume-tier pricing moves month to month with your mix.
* A commitment never gates sending. It is a period-level contract meter on top of the same prepaid wallet your pay-as-you-go usage already draws from. Reaching 100% drawdown does not block traffic; overage simply continues on top.

## 2. Eligible SKUs and commitment levels

A commitment is a negotiated contract term, not a self-serve plan picker. There is no public catalog of commitment levels: the monthly commit amount, the discount percent, and the term dates are agreed with your Devotel account contact against your actual traffic mix (messaging, voice, and the other metered SKUs on your account), then configured on your organization by Devotel. There is intentionally no tenant-writable API for the commitment itself.

What you can read back programmatically is the commitment as configured, via the drawdown meter:

```bash theme={null}
curl -s "https://api.orbit.devotel.io/api/v1/billing/commitment" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

```json theme={null}
{
  "data": {
    "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": { "..." : "see field reference below" }
  }
}
```

The `commitment` block is your enacted term: `monthly_commit_cents` is the spend floor per billing period, `discount_percent` the negotiated rate discount, and `term_start` / `term_end` the contract term the commit renews against. Organizations without a commitment receive `commitment: null` with the period bounds and current spend, so you can poll this endpoint to confirm whether enrollment is live on your org. The full drawdown block and its run-rate projection are documented in [Committed-use drawdown](/concepts/committed-use-drawdown-model#reading-the-meter).

The endpoint requires the `owner`, `admin`, or `billing` role, like the other billing surfaces.

## 3. Forecast your savings before you commit

Never size a commit from a guess. Orbit ships a what-if pricing simulator that replays your own recorded traffic through a candidate rate card; combined with the drawdown meter it gives you everything a commit decision needs. The full worked loop below uses a 12% negotiated discount as the running example.

**Step 1: Establish your current spend and mix.** Read your trailing months from your invoices, or poll `GET /api/v1/billing/commitment` (without a commitment it returns `current_spend_cents` for the period to date). You want a steady-state monthly figure, not a launch-month spike. For this example: \$5,000/month of mostly outbound SMS to one destination.

**Step 2: Replay your traffic at the committed rates.** Run `POST /api/v1/billing/whatif-pricing/preview` over your last 30 days with your live rates scaled by the negotiated discount. A 12% discount on a $0.008 SMS segment is $0.00704:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/billing/whatif-pricing/preview" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "window_days": 30,
    "label": "CUD candidate: 12% committed rates",
    "candidate_card": [
      { "channel": "sms", "country_code": "*", "direction": "mt", "rate_per_unit": 0.00704 }
    ]
  }'
```

Read `totals.current_total_cents` against `totals.candidate_total_cents`: the difference is what your recorded traffic would have cost at committed rates. Check `matched_lane_count` against `lane_count` first; any lane with `candidate_matched: false` kept its current cost, so an unmatched lane understates the discount you would actually receive. The simulator's request shape, lane fields, and coverage rules are covered in [What-if pricing simulator](/guides/whatif-pricing-simulator). For per-channel level comparisons, the [billing cost calculator](/guides/billing-cost-calculator) is the quicker surface.

**Step 3: Compare the savings to the floor risk.** A commit is worth taking when:

```
projected monthly savings  >  true-up you would owe in a realistically quiet month
```

On the example: $5,000 of traffic at 12% off saves $600/month. The same calculation says a month that only ships $3,000 of usage costs you a $2,000 true-up (the commit floor still applies). If your trailing twelve months never dipped below roughly 80% of the candidate commit, the floor risk is small relative to \$600 × 12; if one seasonally quiet month sits at 40%, size the commit to that month instead. The drawdown meter's `projected_shortfall_cents` gives you the live version of this number once enrolled, mid-period, before the true-up lands.

## 4. Enroll

Enrollment is a contract action with your Devotel account contact, not an API call:

1. Bring the forecast from section 3: your trailing monthly spend, your traffic mix, and the commit level you want sized to (conventionally your low month, not your average).
2. Agree the terms: `monthly_commit_cents`, `discount_percent`, and the term (`term_start` / `term_end`).
3. Devotel configures the commitment on your organization. There is no tenant-writable endpoint for it by design; the commit is a contract term, and changes to it go through the same channel as renegotiating the contract.

Confirm enrollment from your side with the meter:

```bash theme={null}
curl -s "https://api.orbit.devotel.io/api/v1/billing/commitment" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

A successful enrollment is visible in the response three ways:

* **The anchor date.** `term_start` is the contract anchor; `period_start` / `period_end` show the billing period the commit draws down against from day one.
* **The discount.** `discount_percent` matches the negotiated figure, and your per-unit charges from `term_start` onward reflect the committed rates.
* **The first committed invoice.** The period ending after `term_start` settles your first committed invoice: metered usage up to the commit, plus a minimum-commit true-up line if that first period undershot.

Your dashboard's billing panel shows the same drawdown meter and self-hides until a commitment exists, so the panel appearing is itself confirmation.

## 5. How committed spend appears on your invoice

Committed-use money is booked as deferred revenue and recognized straight-line over the term; the recognition surfaces are documented end to end in [Revenue recognition and volume tiers](/guides/billing-revenue-and-volume-tiers#4-the-recognition-model). For your finance team's journal mapping, the recognition schedule (`GET /api/v1/billing/revenue-recognition/schedule`) attributes every commitment contract with a stable internal code: `contract_id` is `committed-use` and `source` is `committed_use`, as described in that guide's [journal mapping table](/guides/billing-revenue-and-volume-tiers#5-journal-the-internal-code-mapping). Map those two fields into your chart of accounts once and the commitment posts cleanly every month thereafter.

On the operational side, the commit does not replace your wallet: usage still debits the wallet as it happens, and the commitment meter tracks period-level drawdown against the same ledger. Your invoice at period end nets out to usage at committed rates, bounded below by the commit.

## 6. Break-even calculator, worked example

The break-even question is: at the committed rates, how many units must you ship for the discount to cover the commit? Because the discount applies to your rates, the simpler and more useful form is the true-up break-even: how much usage makes the true-up zero.

Worked example, SMS to one destination:

| Input | Value |
| - | - |
| Live rate | \$0.008 per segment |
| Negotiated discount | 12% |
| Committed rate | \$0.00704 per segment |
| Monthly commit | \$5,000 |

* **Break-even volume** = commit ÷ committed rate = $5,000 ÷ $0.00704 ≈ 710,227 segments/month. Above that volume you are in overage (still at committed rates); below it, the gap to \$5,000 is your true-up.
* **Savings at break-even and above** = volume × (live rate − committed rate). At exactly 710,227 segments that is 710,227 × $0.00096 ≈ $682/month, versus what the same traffic would cost at live rates on pay-as-you-go.
* **Cost of a quiet month** at 500,000 segments: usage bills $3,520 at committed rates and the true-up adds $1,480, so the month costs you the full $5,000 while pay-as-you-go would have billed $4,000. Quiet months are what a commit costs; the commit pays when your months average above the floor.

Run the same two lines against your own mix: pull last month's lane volumes from the simulator's `lanes` array, apply the committed rate per lane, sum, and compare with `monthly_commit_cents`. If the sum sits comfortably above the commit in every trailing month, the commit is free money; if it crosses the commit only in good months, size it down.

## 7. Renewal, cancellation, and what happens when usage misses the commit

* **Renewal.** The commit renews per billing period inside the agreed term (`term_start` to `term_end`). Renegotiating the level, the discount, or the term itself is a contract conversation with your account contact, ideally started a period before the term ends rather than at the boundary.
* **Undershoot.** If actual usage ends the period below the commit, the minimum-commit true-up charges the difference: the commit is a floor, not a target ("use it or pay it"). The meter's `shortfall_cents` and `projected_shortfall_cents` show that exposure live, so it is never a surprise at invoice time.
* **Overshoot.** If usage exceeds the commit, the excess bills on top as overage at your committed per-unit rates; nothing blocks, throttles, or re-prices at the crossing. `overage_cents` / `projected_overage_cents` track it.
* **Cancellation.** The commit holds for its term; there is no mid-term self-service cancellation, consistent with there being no self-service enrollment. Early-exit terms are part of the contract negotiation.

## 8. Pair the commit with auto-top-up and budget alerts

A commitment never funds usage and never blocks sends, so the wallet protections you run today keep doing their job under a CUD, and two of them matter more once enrolled:

* **Auto-top-up.** Committed-rate traffic still pre-flights the wallet balance on every send. A committed account typically ships more volume for the same money, so review your auto-top-up thresholds against the committed-rate burn rather than the old one; a top-up configured for pay-as-you-go volumes can run dry sooner under a CUD. See [Auto-top-up](/guides/billing-auto-topup).
* **Budget alerts and spend caps.** The drawdown meter tells you where the period stands, but threshold alerts are what page a human when pace changes. Keep usage-anomaly and spend alerts armed so an `under_pace` trend (the true-up warning) reaches somebody with time to act, and use tenant-owned spend caps if you want a hard ceiling independent of the contract meter. See [Usage anomaly alerts](/billing/usage-anomaly-alerts) and [Spend caps](/billing/spend-caps).

The combination is the intended posture: the commit sets the price floor, auto-top-up keeps sends flowing, and alerts make the pace visible before month-end settles it.

## Related

* [Committed-use drawdown](/concepts/committed-use-drawdown-model) — the meter reference: full response anatomy, run-rate projection, and degradation guarantees.
* [What-if pricing simulator](/guides/whatif-pricing-simulator) — replay your recorded traffic through candidate rates; the forecasting engine used in section 3.
* [Revenue recognition and volume tiers](/guides/billing-revenue-and-volume-tiers) — how committed-use money is booked (`contract_id: committed-use`, `source: committed_use`) and how volume tiers price breakpoint crossings.
* [Billing cost calculator](/guides/billing-cost-calculator) — quick per-channel cost comparisons while sizing a commit.
* [Auto-top-up](/guides/billing-auto-topup) — keep the wallet funded under committed-rate burn.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.