Commitments

Overview

Commitments define minimum spend requirements on a plan. When a customer’s usage-based charges fall below the committed amount in a billing period, BoxBilling automatically generates a true-up fee to cover the difference. This ensures contractual revenue minimums are met regardless of actual usage.

How commitments work

Plan has commitment ──► amount_cents = 50000 ($500)
        │
        ▼
Billing period ends
        │
        ▼
Usage charges total $320
        │
        ▼
True-up fee added ──► $180 (commitment gap)
        │
        ▼
Invoice total = $500 (meets minimum)

If the customer’s charges meet or exceed the commitment amount, no true-up fee is generated.

Commitment properties

Field	Type	Description
id	uuid	Unique commitment identifier
plan_id	uuid	The plan this commitment belongs to
commitment_type	string	Type of commitment (default: minimum_commitment)
amount_cents	decimal	Minimum spend amount in cents
invoice_display_name	string?	Custom label shown on invoices (max 255 chars)
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Create a commitment

Commitments are created on a specific plan using the plan’s code.

curl -X POST /v1/plans/pro_monthly/commitments \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 50000,
    "commitment_type": "minimum_commitment",
    "invoice_display_name": "Monthly minimum spend"
  }'

Response (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "plan_id": "plan-uuid",
  "commitment_type": "minimum_commitment",
  "amount_cents": "50000",
  "invoice_display_name": "Monthly minimum spend",
  "created_at": "2026-03-08T10:00:00Z",
  "updated_at": "2026-03-08T10:00:00Z"
}

The commitment_type defaults to minimum_commitment if omitted. The invoice_display_name controls how the true-up line item appears on invoices — if not set, a default label is used.

Update a commitment

curl -X PUT /v1/commitments/{commitment_id} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 75000,
    "invoice_display_name": "Updated monthly minimum"
  }'

All fields are optional — only the fields you include are modified. Changes apply to future billing periods.

Delete a commitment

curl -X DELETE /v1/commitments/{commitment_id} \
  -H "Authorization: Bearer $API_KEY"

Returns 204 No Content on success. Removing a commitment stops true-up fees from being generated in future billing periods but does not affect invoices already issued.

List plan commitments

Retrieve all commitments configured on a plan.

curl /v1/plans/pro_monthly/commitments \
  -H "Authorization: Bearer $API_KEY"

Response (200):

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "plan_id": "plan-uuid",
    "commitment_type": "minimum_commitment",
    "amount_cents": "50000",
    "invoice_display_name": "Monthly minimum spend",
    "created_at": "2026-03-08T10:00:00Z",
    "updated_at": "2026-03-08T10:00:00Z"
  }
]

How true-up billing works

During invoice generation, BoxBilling checks each subscription’s commitment:

1. Totals all usage-based charges for the billing period
2. Compares against the commitment’s amount_cents
3. If charges are below the commitment, generates a fee of type commitment for the difference
4. The commitment fee uses the invoice_display_name as its label

The commitment fee appears as a separate line item on the invoice with fee type commitment, distinct from regular charge, subscription, or add_on fees.

Entity relationships

• Plans — commitments are defined on plans and apply to all subscriptions using that plan
• Subscriptions — inherit commitments from their plan; true-up is calculated per subscription
• Invoices — commitment true-up fees appear as line items with fee type commitment
• Fees — commitment fees reference the commitment via commitment_id

API endpoints

Method	Path	Description
POST	/v1/plans/{plan_code}/commitments	Create a commitment on a plan
GET	/v1/plans/{plan_code}/commitments	List commitments for a plan
PUT	/v1/commitments/{commitment_id}	Update a commitment
DELETE	/v1/commitments/{commitment_id}	Delete a commitment