ADR-0057 named promotion approval and consumer implementation request
Revenue is implementing named promotion calculation and immutable redemption snapshots behind a default-off flag. This request seeks agreement on the additive consumer interface before contract publication and production activation. No other domain's repo is edited by Revenue.
Proposed interface
Sales close requests add optional promotion_id on offer or each offer_items entry. Credit-purchase requests add it on each items entry, or at top level for legacy singular purchases. The existing authenticated invoice-link and credit-purchases catalog GET responses add promotions, whose options contain promotion_id, name, discount_type (fixed or percentage), discount_amount_cents and discount_basis_points. Only active Organization-scoped promotions are offered while enabled. No selection retains full catalog pricing. No existing field is deprecated and no consumer migration deadline is necessary.
Fixed amount applies once per complete line. Percentage applies to subtotal, rounded half up once to cents. A discount must leave a positive payable line total. Sales must submit the exact net price; Revenue independently validates it and the payment total. Stacking and custom discounts are unsupported. Credits granted are unchanged. Applied promotion snapshots commit with the order and event; mutable catalog changes and flag rollback do not invalidate successful replay. Provider invoices carry net amounts without applying a second discount.
Asks
Sales and Delivery, acknowledge ADR-0057 and the explicit selection, rounding, and positive-total rules. Declare your consumer implementation commitments in your own reply memos. Finance, acknowledge net per-credit recognition with unchanged credits. Platform, review whether the additive catalog option and existing event totals require any mirror changes; Revenue proposes no event-schema or identity changes.
Revenue will publish the contract extension only after required acknowledgments. Runtime activation remains separately gated on exact deployment, current production alias, flag and provider-total proof. The local backend implementation is not a production-readiness claim.
Analytics questions
Which promotion produced a discount? PromotionRedemption's promotionId and immutable name and terms answer it. What amount was discounted? OrderItem.lineDiscountCents answers it without reducing purchased credits. What value should be recognized per credit? The net lineTotalContributionCents and perCreditValueSnapshotCents answer it; gross catalog price remains in lineSubtotalCents and unitPriceSnapshotCents.
References
- ADR-0057
- Sales ordering surface
- Revenue implementation guide: docs/promotions.md