> ## Documentation Index
> Fetch the complete documentation index at: https://flexprice-mintlify-9d9353d9.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Commitment
> Commitment-based pricing is a flexible billing model that enables customers to commit to a minimum spend amount for each billing period. This pricing strategy provides predictable revenue for businesses while offering customers the flexibility to pay for actual usage beyond their commitment at a premium rate.
### How Commitment Works
When a commitment amount is configured for a subscription:
1. **Commitment Amount**: The minimum amount a customer commits to paying per billing period (e.g., \$1,000/month). This guarantees minimum revenue for the business.
2. **Overage Factor**: A multiplier applied to usage costs that exceed the commitment amount (e.g., 1.5x). When a customer's usage surpasses their commitment, the excess usage is charged at this higher rate.
3. **Usage Calculation**:
* If total usage cost ≤ commitment amount: All usage is charged at standard rates
* If total usage cost > commitment amount: The commitment amount is charged at standard rates, and the excess (overage) is charged at the overage factor rate
## Steps to Add Commitments to a Subscription
1. Click the **Add Subscription** button
2. Scroll down to the **Commitment & Overage** section
3. Define the commitment amount and overage factor
## Understanding True-Up
True-up is a billing mechanism that ensures customers pay their full commitment amount even if their actual usage falls short. When enabled, if a customer's usage doesn't meet the minimum commitment amount, they are charged the difference as a "shortfall" or "true-up" fee.
### How True-Up Works
1. **During Billing Period**: The system tracks all usage and calculates the total usage cost
2. **At Invoice Generation**:
* If usage cost \< commitment amount AND true-up is enabled: A true-up line item is added to charge the remaining commitment amount
* If usage cost ≥ commitment amount: No true-up is needed (standard commitment and overage logic applies)
## Steps to Add True-Up
You can enable true-up for a subscription during the subscription creation process:
1. Click the **Add Subscription** button
2. Scroll down to the **Commitment & Overage** section
3. Define the commitment amount and overage factor
4. Enable true-up using the toggle switch
## Time-of-day commitment buckets
Time-of-day buckets split a windowed commitment into multiple ranges within a UTC day, each with its own commitment value, price, and overage factor. Use them when a single line item needs different rates for peak versus off-peak hours — for example, GPU compute that costs more between 09:00 and 17:00 UTC.
Buckets are configured per subscription line item and require `commitment_windowed: true`. Each bucket covers a half-open `[start, end)` range, and the engine charges the bucket whose window contains the usage timestamp.
**When to use buckets:**
* **Peak/off-peak pricing** — Higher commitment and rate during business hours, lower outside
* **Tiered SLAs** — Different minimum spends for production hours versus maintenance windows
* **Burst capacity** — Reserved capacity at a guaranteed rate during a defined window, overage rate elsewhere
### Bucket fields
| Field | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `start` | `{ "hour": 0-24, "minute": 0-59 }`. The first minute the bucket applies. |
| `end` | `{ "hour": 0-24, "minute": 0-59 }`. The first minute the bucket no longer applies. `24:00` is the only allowed end-of-day value. |
| `price` | Inline subscription-scoped price. Required when creating a new bucket; omit on updates when keeping the existing price. |
| `id` | Server-assigned bucket ID. Provide it on updates to keep the existing bucket and its price. |
| `commitment_type` | `amount` or `quantity` — matches the line item commitment type. |
| `commitment_value` | Minimum spend or quantity for the bucket window. |
| `overage_factor` | Multiplier applied to usage beyond the bucket commitment. Optional. |
| `true_up_enabled` | Charges the shortfall when usage in the bucket window falls below `commitment_value`. |
Buckets must not overlap, and ranges can wrap midnight (for example `{22:00, 06:00}` covers `22:00–05:59`). All times are UTC.
### Example: peak and off-peak commitment
```json theme={null}
{
"commitment_type": "amount",
"commitment_windowed": true,
"commitment_duration": "DAY",
"commitment_time_buckets": [
{
"start": { "hour": 9, "minute": 0 },
"end": { "hour": 17, "minute": 0 },
"commitment_type": "amount",
"commitment_value": "500.00",
"overage_factor": "1.5",
"true_up_enabled": true,
"price": {
"type": "USAGE",
"billing_model": "FLAT_FEE",
"billing_period": "DAY",
"billing_period_count": 1,
"invoice_cadence": "ARREAR",
"amount": "0.10"
}
},
{
"start": { "hour": 17, "minute": 0 },
"end": { "hour": 9, "minute": 0 },
"commitment_type": "amount",
"commitment_value": "100.00",
"overage_factor": "1.2",
"price": {
"type": "USAGE",
"billing_model": "FLAT_FEE",
"billing_period": "DAY",
"billing_period_count": 1,
"invoice_cadence": "ARREAR",
"amount": "0.04"
}
}
]
}
```
### Updating buckets
On `PATCH` of a subscription line item, the bucket array replaces the existing buckets:
* **Keep an existing bucket** — include its `id` and omit `price`. Commitment fields are read from the request, so you can change `commitment_value`, `overage_factor`, or `true_up_enabled` while keeping the original price.
* **Add a new bucket** — omit `id` and include an inline `price`. The server creates a subscription-scoped price and assigns a bucket ID.
* **Remove all buckets** — send `"commitment_time_buckets": []` (an empty array). Omitting the field keeps the existing buckets unchanged.
`commitment_time_buckets` requires `commitment_windowed: true`. Sending buckets on a non-windowed line item returns a validation error.
***