Catalog & pricing
Catalog & pricing
Catalog
A Stripe-style split of Product (what you sell) and Price (how much / how
often — a version):
interface Catalog
{
// resolve, list, and version products and prices
}
InMemoryCatalog is the default. Prices are versioned by effective date: a new
version supersedes the prior, new subscriptions use the most recent version, and
existing subscriptions are invoiced against the version in effect when the
subscription was created — price-pinning / grandfathering by default.
Pricing models
PricingModel selects how a quantity turns into an amount. Flat and per-unit are the
scalar models; the four tiered models price against an ordered list of
PriceTiers carried on the Price (and, for packages, a packageSize):
| Model | Rule |
|---|---|
Flat |
one fixed amount regardless of quantity (billable quantity is 1) |
PerUnit |
unitAmount × quantity |
Graduated |
the quantity is sliced across tiers; each slice is priced at its own tier's rate and the slices are summed (plus any per-tier flat entry fee reached) |
Volume |
all units are priced at the single tier the total quantity lands in (a retroactive volume discount) |
Package |
ceil(quantity ÷ packageSize) whole blocks, each charged the block's flat price (buy in packs of N) |
Stairstep |
a single flat amount for the whole bracket the quantity lands in |
Percentage |
a rate of a reported value, with optional fixed fee, minimum, maximum and tiers by volume (below) |
A PriceTier is { ?int upTo, Money unitAmount, ?Money flatAmount }: upTo is the
tier's inclusive upper bound in units (null marks the final, unbounded tier),
unitAmount the per-unit rate within the tier, and flatAmount a tier fee whose
meaning is set by the model (a graduated/volume entry fee, the package block price,
or the stairstep bracket price).
// Graduated: 0–10 @ €1.00, 11–100 @ €0.80, 101+ @ €0.50
$price = new Price('metered-v1', 'metered', PricingModel::Graduated,
Money::ofMinor(0, 'EUR'), new DateTimeImmutable('2025-01-01'),
tiers: [
new PriceTier(10, Money::ofMinor(100, 'EUR')),
new PriceTier(100, Money::ofMinor(80, 'EUR')),
new PriceTier(null, Money::ofMinor(50, 'EUR')),
],
);
$catalog->priceQuantity('metered', 150, $now); // €107.00 → 10×100 + 90×80 + 50×50
Every tiered model is computed by Pricing\TierCalculator in integer minor units
— only unitAmount × wholeUnits and flatAmount terms, never a division — so no
minor unit is ever rounded away (remainder-safe by construction). It is
deny-by-default: an empty, mis-ordered, negatively-priced, or gap-having tier
set, a package with no positive size/block price, or a quantity that no tier covers
raises MalformedTierSet rather than silently returning zero. priceQuantity() is
the single catalog entry point the quote path uses, so a tiered product prices
through the same call as a flat one; Price::amountFor() does the same for a Price
in hand. Tiered pricing composes with metering: a meter's aggregated billable
quantity (see Metering → billable-metric aggregations)
feeds straight into amountFor().
Percentage prices
PricingModel::Percentage charges a rate of a reported value, such as 1.5% of the
transaction volume a meter sums. Its terms are a PercentagePrice on the Price:
| Term | Meaning |
|---|---|
tiers |
the rate by volume, as PercentageTier { ?int upTo, PercentageRate rate }; one unbounded tier is a single rate |
tierMode |
Graduated charges each slice of volume at its own tier's rate; Volume charges all of it at the tier the total lands in |
fixedFee |
an optional amount per fee unit: an event, or a unit the writer counts |
minimum / maximum |
an optional least charge and cap per period |
A PercentageRate holds a percentage exactly, as parts per million (ofPercent('1.5')
is 15,000), with at most four decimals and at most 100%. The volume and the tier bounds
are in the price currency's minor units.
$terms = new PercentagePrice('DKK', [new PercentageTier(null, PercentageRate::ofPercent('1.5'))],
fixedFee: Money::ofMinor(100, 'DKK'), minimum: Money::ofMinor(5_000, 'DKK'));
$charge = (new PercentageCalculator)->charge($terms, volume: 123_457, feeUnits: 3);
// 1.5% of 1,234.57 = 18.51855, plus 3 × 1.00 = 21.51855 → 21.52, below the minimum → 50.00
$charge->total; // 5000 DKK minor
$charge->bound; // 'minimum'
PercentageCalculator sums every term exactly and rounds the total once, half up,
to a whole minor unit. It never rounds per event or per slice, so many small amounts
cannot each round away to zero. The minimum and maximum then bound the rounded total. A
period with no volume and no fee units is charged nothing, minimum included. Malformed
terms (no tier, tiers out of order, an amount in another currency or below zero, a minimum
above the maximum) raise MalformedPercentagePrice when the PercentagePrice is built.
Price::amountFor($volume) charges a percentage price with no fee units.
Product shapes (ADR-0015)
A Product declares a ProductShape selecting its billing/fulfilment semantics:
Metered— a usage-metered plan (entitlement + real-time metering).Recurring— a rolling subscription: cycle-anchored, prorated, renewing indefinitely. This is the default, so pre-shape catalogs keep their exact meaning.FixedTerm— a registrar-style product bought for a committedTerm(1/2/5 yr) with distinct register/renewal/transfer/redemption pricing and a post-expiry lifecycle. See Subscriptions → fixed-term products.OneTime— a single non-recurring charge.
shape is the last constructor parameter and defaults to Recurring, so it is
backward-compatible.
Term × price-kind pricing (ADR-0015)
A FixedTerm product's catalog is a set of (term × kind) price points. A Term
is a {count, TermUnit} (Day | Month | Year) with calendar arithmetic (addTo,
toIso8601 → e.g. P2Y, equals). A PriceKind is Standard | Register | Renewal | Transfer | Redemption — a .com at P2Y/Register is a different
number than at P1Y/Renewal, and redemption carries a recovery premium.
$price = $catalog->termPriceFor('domain-com', new Term(2, TermUnit::Year), PriceKind::Register, $now);
termPriceFor grandfathers by effective date exactly like priceFor: an instance
registered before a price rise keeps the version effective at its registration.
priceFor resolves only the non-term (Standard) prices, so the two never collide
on a mixed catalog. Recurring/metered prices leave term null and kind at
Standard.
Registry/EPP/DNS provisioning (auth codes, actual transfers) is out of scope — a connector concern. The catalog owns only the commercial price grid.
Pricing operations
Coupon (DiscountType::Percentage or Fixed, with validity) and CouponApplier
discount the net before tax, so the tax base is the discounted amount:
$net = $couponApplier->apply($coupon, $net, $now);
Seller of record
Tax depends on who is selling. A SellerEntity carries its tax registrations
(TaxRegistration), and EntityRouter routes a buyer to the entity registered in
their country, falling back to a default:
interface EntityRouter
{
// route a buyer to the SellerEntity that should be the seller of record
}
DefaultEntityRouter is the multi-entity routing that drives tax resolution in the
quote, which composes cboxdk/laravel-tax for the
actual per-line VAT.