Quantity discount

Scope: PIT and POT, all quantity strategies.

The five configuration decisions

#	Question	Status	Notes
1	How many discounted units?	Available	e.g., 1,000 discounted API calls
2	How often are they refreshed?	Available	Monthly, daily, quarterly
3	What happens to unused units?	Not available	Always use-it-or-lose-it currently
4	When do you pay for overages?	Available	Prepaid or postpaid
5	When do discounted units become available?	Available	The discount has its own date range, constrained to a sub-range of the line item’s duration; it can’t extend beyond it

Configuration fields

Field	Description	Required	Default
`value`	Discounted units per cadence cycle	Yes	N/A
`cadence`	Refresh frequency (P1M, P1D, P3M, etc.)	No	None (per-period)
`prorate_stub`	Reduce pool for partial cadence windows	No	false
`rounding`	Rounding for prorated pool (`floor`/`ceil`/`half_up`)	No	`floor`
`label`	Display label on invoice	No	N/A
`order`	Execution order when stacking multiple discounts	No	N/A

Core calculation

Pool created: fresh pool of value discounted units at each cadence boundary.
Deplete chronologically: periods within the cadence window consume from the pool in order.
Bill the remainder: usage beyond the pool is billable.

Resolution formula: discounted_units = min(period_usage, remaining_pool).

Cadence behavior

Relationship	Example	Behavior
Cadence = billing period	Monthly cadence, monthly bill	Each billing period gets its own pool
Cadence > billing period	Quarterly cadence, monthly bill	Single pool shared across months; depletes chronologically
Cadence < billing period	Daily cadence, monthly bill	Each day gets its own pool; month-end is the sum of daily overages
No cadence (`cadence=None`)	N/A	Functionally the same as cadence = billing period: each billing period gets `value` discounted units, but `prorate_stub` doesn’t apply

Proration

Scenario	Proration?
Contract starts or ends mid-window	Yes, if `prorate_stub=true`
`prorate_stub=false` (default)	No, full pool for partial windows
Full cadence window	No, full pool
`cadence=None`	Not applicable, no cadence window to prorate

pool = value × (window_days / full_cadence_days)
1,000 discounted/month, contract starts Jan 15 (17 of 31 days):
Prorated pool = 1,000 × (17/31) = 548.39

Rounding	548.39 →	Use case
`floor`	548	Favors the business
`ceil`	549	Favors the customer
`half_up`	548	Standard rounding

For POT, pricing proration operates on the dollar amount for a partial period, while discount proration (prorate_stub) operates on the quantity pool. These are different axes and aren’t expected to interact.

Discount stacking

Multiple discounts coexist via the order field. Quantity discounts reduce units first; dollar and percent discounts apply to the resulting amount afterward.

50 discounted (order=1) + 20% off (order=2), 200 calls @ $0.01
Step 1: 200 − 50 = 150 billable units
Step 2: 150 × $0.01 = $1.50
Step 3: $1.50 × 80% = $1.20

Interaction with pricing models

Model	Quantity discount applicable?	Notes
Per-unit (linear)	Yes	Straightforward: discount reduces units, remainder priced at flat rate
Volume (non-linear)	Yes	Discounted units can shift which bracket the customer lands in, sometimes raising the total
Tiered (non-linear)	Yes	Fewer units fill fewer tiers; total is always less than or equal to without the discount
Package	Yes	Fewer units means fewer packages
Flat fee	No	Fixed amount regardless of quantity
Percent	No	Based on monetary input, not units
Step	Yes	Fewer units means fewer steps triggered

Invoice presentation

API Calls (Jan 1–31, 2026)
  Usage:              3,500 calls
  Quantity Discount:  −1,000 calls (First 1,000 discounted)
  Billable:           2,500 calls
  Rate:               $0.001/call
  Amount:             $2.50

Each period produces a breakdown record with: quantity before and after discount, discount applied, and pool before and after.

Risks and edge cases

Scenario	Handling
Cadence > billing period = budget depletion	”500/quarter” depletes across 3 months, not 500/month
Discount order	Quantity discounts reduce units first, then dollar discounts apply

Glossary

Term	Definition
Quantity discount	Discounted units that offset billable consumption or allocation
Pool	Discounted units available within a cadence window; depletes chronologically
Cadence	Refresh frequency for the pool (daily, monthly, quarterly)
Cadence window	Time span covered by one pool instance
Prorate stub	Proportional pool reduction for partial cadence windows
Rounding	How a prorated (fractional) pool resolves to a usable unit count
Discount stacking	Multiple discounts on one product, ordered by the `order` field
Breakdown	Per-period audit record: pool state, discount applied

Out of scope / deferred

Feature	Description
Carryover	`percentage`, `all`, `fixed` strategies with `max_balance` caps
Expiry models	`end_of_grant_period`, `end_of_billing_period`, `end_of_contract`, `custom`
Grant timing	`on_purchase`/`on_payment` triggers; `delay` for trials
Per-event scope	`scope="per_event"`, e.g. “5 discounted per purchase”
Prepaid entitlements	Grant records, dashboard balance, real-time tracking
Batch-based expiry	Independent batches with FIFO consumption
Faucet-and-bucket	Separate grant cadence from expiry boundary
Cross-product discounts	Shared pool across multiple products

Getting started

Product modules

Security

Model context protocol (MCP)

Pricing models

Third-party integrations

Roadmap

The five configuration decisions

Configuration fields

Core calculation

Cadence behavior

Proration

Discount stacking

Interaction with pricing models

Invoice presentation

Risks and edge cases

Glossary

Out of scope / deferred

​The five configuration decisions

​Configuration fields

​Core calculation

​Cadence behavior

​Proration

​Discount stacking

​Interaction with pricing models

​Invoice presentation

​Risks and edge cases

​Glossary

​Out of scope / deferred

The five configuration decisions

Configuration fields

Core calculation

Cadence behavior

Proration

Discount stacking

Interaction with pricing models

Invoice presentation

Risks and edge cases

Glossary

Out of scope / deferred