> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.zenskar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Volume

# Volume pricing

## Concepts

### What volume pricing is

Volume pricing is a pricing model where one single rate applies to all units, determined by which bracket the total quantity falls into. The total quantity picks a bracket, and every unit — including the very first one — is charged at that bracket's rate.

```
VOLUME PRICING:
  Customer uses 150 units
  Brackets: [100, 200, inf] @ [$3, $2.50, $2]
  → 150 falls in bracket 2
  → ALL 150 × $2.50 = $375

TIERED PRICING (same brackets):
  → First 100 × $3 = $300
  → Next 50 × $2.50 = $125
  → Total = $425
```

This is fundamentally different from tiered pricing, where each portion of usage gets its own rate. Volume pricing creates a price cliff at bracket boundaries — buying one more unit can dramatically reduce total cost (for example, 99 units at $5 each is $495, while 100 units at $4 each is $400). This incentivizes customers to commit to higher volumes.

| Aspect                     | Volume pricing                                            | Tiered pricing                            |
| -------------------------- | --------------------------------------------------------- | ----------------------------------------- |
| Rate determination         | Total quantity picks one rate for all units               | Each portion gets its own rate            |
| Price cliff at boundaries? | Yes — crossing a boundary changes the rate for every unit | No — smooth progression                   |
| Invoice display            | Single line item (one rate)                               | Multiple line items (one per tier)        |
| Best for                   | Bulk discounts, committed volume deals                    | Progressive rates, usage-based incentives |

Brackets can run in two directions: descending prices (standard — higher volume means a lower per-unit price) or ascending prices (overage or penalty pricing — higher volume means a higher per-unit price).

### How PIT volume pricing handles accumulation

PIT products are charged per consumption event, and usage can accumulate across billing periods within a tier reset window. The tier reset period controls how long cumulative usage builds up before resetting back to zero, and it always anchors to the product's anchor date.

| Scenario                                                     | Behavior                                                                                   | Retroactive adjustments?                                                         |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Tier reset = billing period (both monthly)                   | Each billing period is independent                                                         | No                                                                               |
| Tier reset > billing period (annual reset, monthly billing)  | Usage accumulates across billing periods; the bracket may change as cumulative usage grows | Yes — credit notes (descending prices) or additional invoices (ascending prices) |
| Tier reset \< billing period (weekly reset, monthly billing) | Each reset period is shown as a separate calculation on the invoice                        | No                                                                               |

When tier reset is longer than the billing period and cumulative usage crosses a bracket boundary in a later period, prior periods must be corrected — since volume pricing promises all units get the same rate, the engine retroactively reprices everything already billed within the current tier reset window. This happens automatically and can't be turned off for PIT volume pricing.

```
Brackets: [100, 1000, inf] @ [$3, $2.50, $2]
Tier Reset: Annual | Billing: Monthly

JANUARY: Usage 60 (cumulative: 60) → Bracket 1 @ $3.00 → Invoice: $180.00

FEBRUARY: Usage 50 (cumulative: 110) → Bracket 2 @ $2.50 ← bracket changed
  Retroactive adjustment for January: 60 × ($3.00 − $2.50) = $30.00 credit
  February charges: 50 × $2.50 = $125.00
  February invoice: $125.00 − $30.00 = $95.00
  Running total: $180 + $95 = $275.00 → matches 110 × $2.50 = $275.00 ✓

JANUARY (NEXT YEAR): Tier reset — cumulative resets to 0, starts fresh at bracket 1
```

### How POT volume pricing differs

POT products are charged for access over a time period (seats, licenses, servers) — price is expressed per unit per period, like \$20/seat/month. Quantity here is typically a current snapshot rather than an accumulating total, and changes happen through amendments rather than usage events.

| Aspect                 | PIT volume                                              | POT volume                                                      |
| ---------------------- | ------------------------------------------------------- | --------------------------------------------------------------- |
| Quantity nature        | Cumulative consumption                                  | Current snapshot                                                |
| Price expression       | Per unit                                                | Per unit per period                                             |
| Tier reset period      | Required config for cross-period accumulation           | Open — currently defaults to billing period                     |
| Bracket change trigger | Cumulative usage crossing a boundary                    | An amendment (adding or removing seats) crossing a boundary     |
| Retroactive repricing  | Yes — always on, when tier reset exceeds billing period | Not applicable — amendments don't trigger retroactive repricing |

When an amendment crosses a bracket boundary mid-period, POT performs a forward split rather than a retroactive correction: the period before the amendment is credited at the old bracket rate for its remaining days, and the period after the amendment is charged at the new bracket rate for all units (old and new combined). The pre-amendment portion is never retroactively repriced.

```
Brackets: [10, 50, inf] @ [$25, $20, $15] per seat/month
Billing: Monthly

Jan 1: 30 seats → Bracket 2 → all at $20/seat/month
Jan 15: Amendment +25 seats (55 total) → Bracket 3 → all at $15/seat/month

  Jan 1–14 (14 days, original quantity):
    Prorated price: $20 × (14/31) = $9.03/seat → Charge: 30 × $9.03 = $270.97
    (stays at bracket 2 rate — not retroactively repriced)

  Jan 15–31 (17 days, post-amendment):
    Prorated price: $15 × (17/31) = $8.23/seat → Charge: 55 × $8.23 = $452.42
    (all 55 seats at bracket 3 rate)

  January total: $270.97 + $452.42 = $723.39
  Feb 1 (full month): 55 × $15 = $825.00
```

> **Review note:** POT volume pricing behavior above is derived from PIT implementation docs and conceptual design work, and needs engineering validation before being treated as final.

### Proration

Proration works differently depending on whether the product is PIT or POT, and which axis it applies to:

| Scenario                                       | What's prorated                                               | Bracket based on            |
| ---------------------------------------------- | ------------------------------------------------------------- | --------------------------- |
| POT: mid-period start or end                   | Per-unit price (by days), then × quantity                     | Full quantity, not prorated |
| POT: mid-period amendment                      | Per-unit price per segment (by days), then × segment quantity | The segment's quantity      |
| PIT: prepaid, fixed quantity, mid-period start | The quantity grant itself (by days)                           | The prorated quantity       |
| PIT: postpaid, metered, mid-period start       | Nothing — actual usage is used                                | Actual usage                |

For POT, the bracket is always determined by the full, un-prorated quantity — it's the per-unit price that gets scaled down for a partial period, not the quantity used to pick the bracket. For PIT, it's the reverse in the prepaid case: the quantity grant itself shrinks for a partial period, and that shrunk quantity is what determines the bracket.

### How it interacts with other pricing features

Volume pricing can be combined with other features, and the order they're applied in matters:

```
1. Raw usage
2. Quantity discount (if configured) → adjusted quantity
3. Minimum quantity (if configured) → effective quantity
4. Bracket determination + volume calculation → amount
5. Retroactive adjustments (PIT only, when tier reset > billing period)
6. Minimum spend commitment (if configured) → max(volume amount, minimum spend)
7. Percentage / fixed discount (if configured) → final amount
8. Final total
```

A quantity discount applied before bracket determination can shift which bracket the customer lands in — sometimes lowering the bracket into a *higher* rate, which is correct behavior but can be surprising to a customer reading their invoice. A minimum quantity commitment, if usage falls short of it, uses the minimum for both the bracket lookup and the billing calculation, not just the final amount.

## How to configure volume pricing on a line item

1. On the line item, set the pricing model to volume.
2. Define the bracket boundaries as an ascending array of end-points, with the final boundary set to infinity (`inf`) — for example, `[100, 200, inf]`.
3. Define a price for each bracket, with one price per boundary — for example, `[$3, $2.50, $2]`.
4. Choose whether each boundary is inclusive (the boundary value belongs to the current bracket; this is the default) or exclusive (the boundary value belongs to the next bracket).
5. For PIT products, set the tier reset period if it should differ from the billing period — for example, an annual reset on monthly billing. Leave it unset to default to the billing period.
6. For POT products, the tier reset period currently defaults to the billing period and isn't independently configurable.
7. Optionally set a breakdown frequency to control invoice display granularity — this is presentation only and never affects the calculation.
8. Save and preview the invoice to confirm bracket assignment and any retroactive adjustments behave as expected.

## Reference

### Bracket configuration

**Validation rules**

| Rule                                      | Valid example          | Invalid example        |
| ----------------------------------------- | ---------------------- | ---------------------- |
| Must end with `inf`                       | `[100, 200, inf]`      | `[100, 200]`           |
| Boundaries strictly ascending             | `[100, 500, inf]`      | `[500, 100, inf]`      |
| At least 2 boundaries                     | `[100, inf]`           | `[inf]`                |
| Prices array matches boundaries in length | 3 boundaries, 3 prices | 3 boundaries, 2 prices |
| All prices positive                       | `[$0.10, $0.05]`       | `[$0.10, -$0.05]`      |

**Input format** — brackets are defined by end-point boundaries; each value is the upper limit of a bracket, and the last bracket must end with `inf`.

```
INPUT:
  Boundaries: [100, 200, inf]
  Prices:     [$3,  $2.50, $2]

INTERPRETED AS:
  Bracket 1:  0 to 100    @ $3.00/unit
  Bracket 2:  101 to 200  @ $2.50/unit
  Bracket 3:  201+        @ $2.00/unit
```

**Inclusive / exclusive boundaries** — inclusive is the default.

| Setting             | Boundary = 100      | Meaning                              |
| ------------------- | ------------------- | ------------------------------------ |
| Inclusive (default) | 100 is in bracket 1 | Bracket 1: 0–100, Bracket 2: 101–200 |
| Exclusive           | 100 is in bracket 2 | Bracket 1: 0–99, Bracket 2: 100–200  |

**Optional configuration**

| Field               | Description                                                                                  | Default                   |
| ------------------- | -------------------------------------------------------------------------------------------- | ------------------------- |
| Tier reset period   | When cumulative usage resets (PIT only). Open for POT — currently defaults to billing period | Billing period            |
| Breakdown frequency | Invoice display granularity. Must be ≤ billing period. Presentation only                     | None                      |
| Billing offset      | Prepaid or postpaid                                                                          | System default            |
| Usage aggregate     | Links metered quantity to the volume bracket                                                 | Default per pricing model |

### Order of operations (full calculation stack)

```
1. Raw usage — quantity from aggregate or fixed input
2. Quantity discount (if configured) — adjusted quantity = raw usage − quantity discount
3. Minimum quantity (if configured) — effective quantity = max(adjusted quantity, minimum quantity)
4. Bracket determination + volume calculation — find the bracket, get its rate, amount = effective quantity × rate
5. Retroactive adjustments (PIT only, tier reset > billing period) —
   descending prices: credit note = prior qty × (old rate − new rate)
   ascending prices: additional invoice = prior qty × (new rate − old rate)
6. Minimum spend commitment (if configured) — amount = max(volume amount, minimum spend)
7. Percentage / fixed discount (if configured) —
   fixed: amount − discount (floored at $0)
   percentage: amount × (1 − discount%)
8. Final product total — ready for invoice
```

### Scope

| Dimension          | Coverage                                                                    |
| ------------------ | --------------------------------------------------------------------------- |
| Product types      | Point-in-time (PIT) and period-of-time (POT)                                |
| Bracket directions | Descending prices (volume discounts) and ascending prices (overage/penalty) |
| Quantity subtypes  | Homogeneous (fungible units) — heterogeneous deferred                       |

### Glossary

| Term                   | Definition                                                                                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bracket                | A range within which a specific rate applies; in volume pricing, all units get the bracket's rate                                                             |
| Tier reset period      | The window over which PIT cumulative usage accumulates before resetting. Defaults to billing period for POT (open for design)                                 |
| Retroactive adjustment | Automatic repricing of prior billing periods when a bracket changes within a tier reset window (PIT only, when tier reset > billing period)                   |
| Credit note            | A billing document reducing the amount owed, issued when a bracket upgrade lowers the rate (descending prices)                                                |
| Additional invoice     | A billing document increasing the amount owed, issued when a bracket upgrade raises the rate (ascending prices)                                               |
| Forward split          | POT behavior where an amendment creates two segments — pre-amendment at the old rate, post-amendment at the new rate — with no repricing of the prior segment |
| Price cliff            | The phenomenon where crossing a bracket boundary causes a large change in total cost                                                                          |
| Breakdown frequency    | Invoice display granularity — presentation only, never affects calculation                                                                                    |

### Risks and edge cases

| Scenario                            | Handling                                                                                                                            |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Credit exceeds current charges      | When a retroactive credit for prior periods exceeds the current period's charges, the invoice subtotal can be negative              |
| Ascending prices surprise customers | Additional charges for past usage can be unexpected; clear communication is important when configuring ascending (overage) brackets |
| Quantity discount shifts bracket    | Free units can push a customer into a lower bracket with a higher rate — correct behavior, but can be confusing on the invoice      |

### Open questions

| # | Question                                                                                                                                                      | Status |
| - | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| 1 | Tier reset period for POT isn't fully designed yet; it currently defaults to billing period                                                                   | Open   |
| 2 | For on-demand POT volume pricing purchased as a one-time event, what governs the expiry of that purchase — contract end, a fixed duration, or something else? | Open   |

### Out of scope / deferred

| Feature                                | Description                                                                                                     |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Heterogeneous products                 | Unique-identity units (e.g., reports, documents) with deduplication before bracket determination                |
| Entitlement lifecycle                  | Quantity-based grants, rollover, and cost-basis tracking                                                        |
| Cross-product volume aggregation       | Shared brackets across multiple products, with optional normalization for different unit types                  |
| On-demand periodic evaluation          | On-demand purchases accumulating within a tier reset period (currently per-purchase only)                       |
| Mid-contract bracket changes           | Changing the bracket structure itself during an active tier reset period, as distinct from a quantity amendment |
| Prorated brackets for mid-period joins | Bracket boundaries scaled proportionally for customers joining mid-tier-reset-period                            |
| Turn-off retroactive adjustments       | An option to disable retroactive repricing for PIT volume pricing                                               |

*(Placeholder: status of open questions and deferred items should be confirmed before this doc is published externally.)*