Calculate Marginal Usage Fees Without Repricing Earlier Transactions

A tariff says the first 100 transactions are free, the next 900 cost 2 cents each, and further transactions cost 1 cent each. For 1250 transactions, multiplying everything by the last rate produces 1250 cents. Allocating each band produces 2050 cents. Both calculations can describe a pricing method; only one matches a marginal tariff.

This tutorial makes the method visible before writing a posting proposal. You will inspect occupied bands, preserve fractional cents, apply one rounding decision, and explain why the final fee changed. Operations can answer a charge query with a trace. Engineers can reject a malformed schedule or an inapplicable tariff before returning a plausible number.

All Cedar tariffs, usage counts and events below are synthetic teaching inputs. Arithmetic is author-derived. The official Stripe tiered-pricing documentation supports the distinction between graduated per-band and whole-quantity volume methods. Our exact tariff, zero-usage exemption, bounds and rounding are selected choices; this is not a Stripe integration or an actual bank's fee schedule.

Decide what a tier means

In the canonical marginal method, entering another band changes the rate for the additional units. Earlier transactions keep their earlier allocation. Transaction 1001 costs 1 cent here; it does not change the 900 transactions already charged 2 cents.

The comparison method selects the bracket reached by total quantity and applies its rate to all units. At 1000 transactions its 2-cent bracket charges 2000 cents. At 1001 its 1-cent bracket charges 1001 cents. A decreasing total at that boundary is possible under this whole-amount design. Do not repair it into a marginal formula while claiming to implement the same contract.

Our marginal tariff also caps the rounded fee at 2000 cents. The final canonical proposal is therefore 2000, or USD 20.00. The cap explains the 50-cent adjustment from the raw 2050. It does not turn the underlying method into a whole-amount bracket.

Open the full-size tier comparison. Notice which units keep the 2-cent rate when total usage passes 1000.

Put the boundaries in the data

Represent each tier with a cumulative upper bound and a per-unit rate. The first upper is 100, the next 1000, and the final upper is null for unlimited. Lower bounds are implied by the preceding upper, beginning 0. Strictly increasing uppers prevent overlaps and empty bands; an unlimited band anywhere except last is invalid.

Exactly 100 transactions occupy the free band. At 101 only one unit enters the next band, so fee is 2 cents. At 1000 the allocation is 100 free and 900 charged 2 cents, or 1800. At 1001 the extra unit adds 1 cent, giving 1801. These equality cases tell you more about the contract than a single large example.

For marginal tier i, allocation is max(0,min(quantity,upper_i)−lower_i), treating an unlimited upper as the total quantity. Sum allocations and verify they equal total usage. The whole-amount branch instead assigns all quantity to its selected bracket and zero to the others. Both return the same ordered diagnostic shape so a reader can compare them directly.

Preserve fractions until the aggregate is ready

Rates use micro-minor units:1000000 means one cent per transaction. A rate of 250000 is one quarter of a cent. This unit is a selected precision convention, not an annual rate or a percentage of a deposit balance. Quantity is an integer transaction count; neither quantity nor money is accepted as a numeric JSON float.

Two quarter-cent units produce exactly 1/2 cent. The selected half-even rule rounds that to 0. Three produce 3/4 cent and round 1. More subtly, two different tiers each contributing 1/2 cent sum to 1 cent. Rounding each tier individually to 0 would lose the complete fee.

The reference sums exact integer micro-minor charges first, reduces the raw fraction, and rounds once. It returns the residual between exact and rounded amounts. Then it applies the positive-usage minimum and cap. That separates a rounding adjustment from a contractual bound adjustment. It also keeps huge integer quantities exact beyond JavaScript's safe Number range.

State zero, minimum and cap rules explicitly

For positive usage, a minimum 500 can raise a 2-cent rounded fee to 500. With zero usage, this tariff's exemption keeps fee at 0 even when the minimum is 500. Other products may define a base fee; this example has none. The source documentation's flat-fee rules are not silently imported.

Minimum must not exceed cap. Both are whole minor-unit values. Applying bounds after one aggregate round is part of the versioned contract. If a product chooses another order, it needs a different implementation profile and boundary tests. The next tutorial's Minimum-Balance Fee is also a different question: it measures daily account balances rather than imposing a lower bound on a usage charge.

The validation branch covers the whole request. A bad final band must not leave a caller with a partial total from earlier bands.

Use the tariff that actually covered the period

The example aggregation period is 1 October through the exclusive 1 November boundary. A complete usage receipt arrives just after that boundary and no later than the requested knowledge cutoff. The tariff covers the whole period and was available before it began.

A newly announced November tariff cannot be applied to October just because the calculation runs later. An in-period schedule change is unsupported by this one-version profile and must be split or handled by another explicitly defined method. Currency and measure unit must match. A dollar amount is not a transaction count; an EUR tariff is not a USD tariff.

These checks still rely on trusted source completeness. A scalar count and receipt ID cannot prove that every transaction was counted exactly once or that no superseding tariff was omitted. The host must establish that evidence. The calculator explains a supplied complete aggregate; it does not manufacture its provenance.

Separate fee calculation from accepted posting

A supported positive proposal debits the customer's deposit liability on the bank's books and credits fee income. That reduces the liability and increases income. Read Double-Entry Posting Engine for that perspective and Idempotent Journal Posting for the durable business identity boundary.

This function performs no charge. A host still checks actual chart, account scope, entitlement, capacity, economic/source/booking clocks and stable journal identity. Zero yields no journal legs. If an exact result exceeds the posting engine's per-leg amount limit, the fee remains inspectable while proposal status is amount-limit and legs are empty. A mathematical result must not masquerade as a posting-ready instruction outside its interface limits.

Verify the trace, then inspect the lab

The fixture download supplies 101 independently authored full expected outputs. Python and TypeScript match every result and rejection with strict compilation. Behavioral tests also check allocation conservation, marginal monotonicity, the whole-amount boundary decrease and detached outputs. Validation evidence records the actual local checks and separates visitor acceptance.

Run the supplied Python example from the topic directory with python examples/run_example.py. It loads the complete canonical request, rather than hiding tariff dates or usage provenance in defaults. The calculation and output inspection are:

request = next(case["input"] for case in cases["cases"]
               if case["id"] == "canonical-1250-capped")
result = calculate_tiered_fee(request)
assert result["code"] == "FEE_CALCULATED"
assert result["fee"]["fee_minor"] == "2000"
for band in result["trace"]:
    print(band["allocated_quantity_units"], band["exact_segment_fee"])

The allocation quantities are 100, 900 and 250. Inspect the exact segment fractions before the final proposal; a final amount alone cannot explain the pricing method. Python and TypeScript use the same request and complete expected result in their shared fixtures.

The guided lab lets you inspect the canonical allocation, boundary quantities, fractional rounding and an invalid schedule. Method changes recalculate from the same reference. The static comparison and exact table preserve the lesson without motion.

Historical-example decision: not useful for the selected arithmetic. A real issuer example would need the complete applicable contract, units and source chronology; no such event is invented. You can now explain why a usage fee has its amount and what must be verified before posting it. Continue with Minimum-Balance Fee for a calendar-based threshold decision and its one-period identity.