Skip to main content
A quantity bound is a subscription adjustment that sets a floor or a ceiling on the quantity one price bills for a period. Use it where a contract commits the customer to a quantity rather than to an amount: a minimum seat count, a minimum number of entities, or a cap on how much usage you bill. You create a bound on the subscription, against one price:
Use maximumQuantity the same way for a cap.

​
A contracted minimum

An order form commits the customer to a quantity per SKU, and the money follows from it: Create one minimumQuantity per price. The customer can use fewer than they contracted — or none at all — and each line still bills the contracted quantity. A 2% percentageDiscount on the same subscription is then taken on £910.00, because the bound applies before any discount. If the customer uses more than the minimum, the line bills what they used. A bound only ever constrains a quantity; it never fixes one.

​
How a bound is measured

A bound is measured over the target price’s own billing period, not per invoice line. Where a period is split into several lines — you changed the seat count mid-month, for example — the lines are measured together, and each counts for its share of the period. Two half-month lines of 2 seats each measure 2 seats for the month, not 4. Applying a minimum of 4 raises both lines, so the month bills the equivalent of 4 seats for the whole month. An invoice that carries two periods for one price is measured as two commitments. A delayed collection run therefore never halves a monthly minimum. A short period does not scale the bound. A minimum of 4 stays 4 over a part period, so a subscription starting mid-month still owes its full contracted quantity for that month.

​
Several bounds on one price

Bounds do not add up. Where several apply to the same price and period:
  • The greatest minimum is the one that binds.
  • The least maximum is the one that binds.
Two minimums of 4 and 6 give a floor of 6, never 10. Creating the same bound twice therefore changes nothing. You cannot create a minimum that is above an overlapping maximum on the same price. The request is rejected and names the bound it conflicts with. End or change that one first.

​
What a bound can target

A bound names exactly one price of the subscription. It may target:
  • a licensed price, such as a seat or an entity;
  • a metered price, where the bound is a floor or a cap on billed usage;
  • a price whose supply is outside the scope of VAT, such as a cashback.
A price that bills once rather than per period is refused: a commitment is a rate of consumption over repeating periods, and a one-off charge has no period to measure it over.

​
When the price changes

A bound stays attached to its charge when the price the charge bills under changes. This happens when a floating subscription moves to a new plan version, and when you edit a price that a subscription on an older version still bills. The bound then lists both prices in targetPriceIds, and it applies to whichever one a period bills under. You do not need to create the bound again.
A maximumQuantity on a charge can make an invoice fail to close, where the invoice also carries a usage-scaled rebate whose amount then exceeds the charges. Cap the rebate’s price as well, and the invoice closes.

​
Bounds and metered usage

On a metered price, a bound changes what you bill and never what was measured. The line reports the bounded quantity as its quantity and keeps the measured figure separately, so an invoice can always say what the customer actually used. A usage credit on a line already sitting at its floor therefore takes nothing off. That is what a commitment means: the customer owes the contracted quantity whether or not they used it.

​
Ending a bound

Delete the adjustment. See the API reference for what the two responses mean:
  • 204 — no issued invoice has billed it, and the bound is removed.
  • 200 — an issued invoice has billed it, so the bound is shortened to the end of the last period it was billed on, and the response carries it with its new window.
Neither changes an invoice that has already issued.
A bound is a term of one deal, so it lives on the subscription rather than on the plan. Create one per subscription that contracted it.