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

{
  "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.

---