Committed Use Plans
Status: Roadmap. The conceptual model is documented here. Public REST endpoints described below are not yet wired into the API router (no handler is registered for these paths). The page describes the planned shape; treat any code samples as illustrative pending implementation.
A committed use plan (CUP) lets a customer pre-commit to a minimum usage quantity over a term in exchange for a discounted rate. Usage within the commitment is billed at the discount; usage above it is "overage" and bills at the standard rate. The customer is billed for at least the commitment amount, even if actual usage falls short.
Why this matters. Enterprise customers want budget certainty and volume discounts; pure pay-as-you-go can't deliver either. Committed use plans give the customer a discounted rate in exchange for a minimum quantity over a term, with overage pricing for usage above the commitment - giving sales a closing tool, finance a forecastable revenue floor, and the customer a predictable monthly minimum. The same model supports a cloud platform offering 12-month CPU-hour commitments, an API provider negotiating annual call-volume deals, a SaaS vendor selling pre-paid seat blocks, and a telecoms operator structuring multi-year minute commitments with overage fallback.
When to offer a CUP
- Customer with predictable consumption who wants budget certainty
- Migrating an enterprise contract that already includes a volume guarantee
- Closing larger deals by trading discount for commitment
CUPs are an alternative to flat-fee tiers - useful when the customer wants the safety of pay-as-you-go with the savings of a long-term deal.
Anatomy
| Field | Description |
|---|---|
customer_id | The customer this commitment binds |
subscription_id | The subscription it attaches to |
product_id / metric_key | Which metered product the commitment applies to |
committed_quantity | Minimum quantity per commitment period |
commitment_period | month, quarter, year |
term_months | Length of the commitment in months |
committed_unit_amount | Discounted per-unit price |
overage_unit_amount | Per-unit price for usage beyond the commitment |
start_date / end_date | When the commitment is in effect |
status | active, paused, expired, cancelled |
Billing flow
At the end of each commitment_period:
- Aggregate the customer's actual usage for the bound
(product, metric_key)over the period. - Bill max(actual usage, committed_quantity) units at
committed_unit_amount. - If actual usage exceeded the commitment, bill the difference at
overage_unit_amount. - Resulting line items appear on the regular invoice for that period.
Worked example
- 12-month commitment: 1,000,000 API calls/month at $0.0005/call (50% off the $0.001 standard rate)
- Month with 800,000 calls: billed
1,000,000 × $0.0005 = $500(committed minimum) - Month with 1,200,000 calls: billed
1,000,000 × $0.0005 + 200,000 × $0.001 = $700(commitment + overage)
Creating a CUP
Code
Amounts are minor units (cents).
Pausing and cancelling
Pausing keeps the commitment alive but skips billing for the paused window (typically used during service outages or contractual disputes). Cancelling ends the commitment immediately and falls the customer back to standard rates from the next period.
Multi-product commitments
A customer can hold multiple CUPs simultaneously - one per (product, metric_key). Aggregation respects whatever filters the underlying aggregator carries, so a CUP for "premium API calls" only counts events that match that aggregator.
End-of-term
When the term ends, the CUP transitions to expired and the subscription falls back to standard pricing. Auto-renewal is opt-in: enable it on the CUP to roll into a new term automatically with the same committed quantity (or a renegotiated one).
Next steps
- Usage Metering - the metric stream CUPs aggregate from
- Pricing Models - the standard-rate fallback used for overage
- Subscriptions - what CUPs attach to
- API Reference - Committed Use Plans