Copy page

Subscriptions

Prepaid usage commitments

A usage commitment turns a metered line into a prepaid one: the customer pays for a committed quantity up front each billing period, and at period close the actual metered consumption is settled against it. Overage bills the difference as a true-up line; underage is either kept or credited back, per line. A commitment always follows its price's cadence — a yearly prepaid commitment is a commitment on a yearly price, with per-period settlement along the way.

Configuration

Four fields on a usage line, set at assignment via productOverrides, as defaults on the plan's phase products, or later through an edit-products change:

Field	Values	Effect
committedQuantity	decimal ≥ 0	The quantity billed up front each period. null = ordinary metered billing.
usageCarryoverMode	reset | track_actual | ratchet_up | ratchet_down	How next period's committed quantity is derived at settlement. Defaults to reset.
underageMode	forfeit | refund	What happens to unused committed units at settlement. Defaults to forfeit.
minimumCommittedQuantity	decimal ≥ 0, ≤ committedQuantity	Floor for the downward-capable modes. Requires committedQuantity.

POST /v1/subscriptions — see the API Reference for the full schema:

Code
curl -X POST 'https://api.ledgerbee.com/api/v1/subscriptions' \
  -H 'x-api-key: <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": "0190abcd-1111-7000-8000-000000000001",
    "planId": "0190abcd-2222-7000-8000-000000000002",
    "startDate": "2026-08-01",
    "productOverrides": [
      {
        "priceId": "0190abcd-3333-7000-8000-000000000003",
        "committedQuantity": 100,
        "usageCarryoverMode": "ratchet_up",
        "underageMode": "forfeit"
      }
    ]
  }'

Carryover modes

With committed C, actual A, floor F, next period's committed quantity is:

Mode	Next committed	Use for
reset	The agreed quantity, always	A fixed prepaid allowance.
track_actual	max(A, F)	Prepayment that follows usage both ways.
ratchet_up	max(C, A)	Grows with usage, never shrinks — the high-water mark.
ratchet_down	max(min(C, A), F)	Shrinks with usage, never grows.

The tiered-price ratchet — once consumption reaches a tier, the customer can't drop back below it — is ratchet_up combined with forfeit.

Billing mechanics

The commitment bills as a usage_commitment line on the period's advance invoice, priced like any other line (custom price, else tier math, else the unit price — at the committed quantity). At period close the settlement emits a usage_true_up line: positive for overage, negative for a refund-mode underage. Both render as usage lines on the invoice.

• A mid-cycle start bills the full first commitment un-prorated: the customer prepays the full committed quantity for the partial first period, and the settlement trues it up against that period's actual usage.
• Usage events recorded after a period settles count toward the next open period — a settled period is never reopened.
• Forfeiture is final: with underageMode: forfeit, unused committed units do not roll over and are not credited. The one exception is a period whose service window never opened — see below.
• Cancelling settles the open period immediately, against usage up to the cancellation date and against the full committed quantity — the commitment is not prorated down to the days served. Overage bills; a refund-mode underage is credited. This happens on every cancellation, including one that requests no proration refund. Usage recorded after the period's own end is never counted against it, however late the cancellation falls.
• A period the cancellation lands before is returned in full, whatever underageMode says. This is reachable through a send offset, which prebills the next period days ahead: cancel inside that window and the customer has paid for a service period that never began, so there is nothing to forfeit.
• Removing the committed price settles its open period rather than stranding it. This covers both a product edit that drops the line and a plan replacement onto a plan that does not meter it: the closing period is trued up on the terms it was sold under, and a refund-mode underage is credited.
• Replacing the plan with one that meters the same price carries the commitment forward: the closing period still settles, and a ratchet_up level the customer has reached survives the change.

Refunds are credit notes

A refund-mode underage is issued as a credit note targeting the invoice that billed the commitment — there is no cash-refund rail. When that invoice is still a draft (a tenant holding invoices for manual send), the credit note is deferred and issued by a later billing run once the invoice exists to credit, so a refund credit note can trail its settlement by a run.

The credit note is addressed to the customer that paid for the window being settled, which is not always the customer paying now. If the payer changed mid-window — a subscription moved onto a parent's consolidated invoice, or detached from one — the refund follows the customer whose invoice carried the prepayment, and the incoming payer is billed in full for its own window.

Reading settlement state

• subscription.billed webhook payloads carry a usageCommitment object (committedAmount, trueUpAmount) when the invoice includes commitment lines.
• The upcoming-invoice preview returns commitmentNextPeriods — per line, the quantity the next period will bill after carryover — so a ratchet_up increase is visible before it bills.
• Each settlement writes a subscription.usage_commitment_settled event on the subscription's activity log with the actual quantity, the true-up amount, the underage outcome, and the derived next committed quantity.

Errors & failure states

Condition	What you observe	Fix
Commitment on a non-usage price	400 SUBSCRIPTION_COMMITMENT_REQUIRES_USAGE_PRICE	Only set commitment fields on lines whose price has a meter.
Commitment on an arrears-billed subscription	400 SUBSCRIPTION_COMMITMENT_REQUIRES_ADVANCE_BILLING	Commitments prepay a period, so the subscription must bill in advance.
Floor without a commitment, or floor above it	400 SUBSCRIPTION_COMMITMENT_FLOOR_INVALID	Send minimumCommittedQuantity only alongside committedQuantity, with 0 ≤ floor ≤ committedQuantity.