Guide

Discount after pricing resolves.

A discount never changes the underlying rate. It is a named, time-bound deduction applied on top of whatever price the resolver chain already produced — computed at invoice-line time, fully audited, and reversible without touching the base pricing at all.

Definitions vs. instances

Discounting uses a library/instance split, the same shape as a coupon template versus a redemption:

Discount Definition

A reusable, tenant-scoped template — type (Percentage or Fixed), a value (per currency for Fixed), and a duration rule. It has no target and affects nothing on its own.

Discount Instance

Terms applied to one target on one subscription — the subscription’s base price, a specific Variable Component, or the whole invoice. An instance’s terms can come from a library definition or be defined inline as a one-off (see below), but either way the instance itself is what actually reduces an invoice.

Stopping a definition blocks it from being applied again but leaves existing instances untouched. Archiving is destructive to any still-active instance built from it — the dashboard runs a check and shows you exactly which subscriptions would lose their discount before you confirm.

Source: reusable vs. one-off

Independent of duration — where an instance’s terms come from when you apply it from a subscription’s Discounts card, while creating a subscription, or by asking the Revvly Assistant.

From the library

Pick an existing Discount Definition. The instance inherits its type, value, and duration as a snapshot — later edits to the definition don’t reach back into deals already applied.

One-off

Define the type, value, and duration inline, scoped to this one subscription only. Nothing is written to the library, and no other subscription can reuse it — the terms live only on this instance.

Reach for a library discount when you expect to grant the same terms to more than one customer — a launch promo, a referral credit, a standard win-back offer — so it shows up in the tenant-wide analytics and expiring-discounts view as one named thing across every subscription it’s applied to. Reach for a one-off when the terms are truly bespoke to this customer and you have no intention of reusing them — a support-escalation credit, a one-time goodwill gesture, a rate negotiated in a call that doesn’t belong in the shared library. A one-off can still use any duration, including FOREVER; “one-off” describes where the terms are defined, not how long the discount lasts.

Either way, applying an instance to a subscription requires a reason, and both paths are cancellable independently — cancelling a one-off has no effect on anyone else, since nothing about it was ever shared.

Duration

How long an instance keeps applying once it’s attached to a subscription.

First invoice only

Applies to one billing-cycle invoice, the next one the subscription raises, then expires automatically. Applied while a subscription is being created, that is its first invoice. Typical for a signup incentive.

Fixed number of renewals

Applies to a set number of billing-cycle invoices (e.g. 3 months off), counting the next invoice as the first, then expires automatically. Mid-cycle adjustment invoices never use up the count. The instance tracks appliedCount against the count.

Forever

Applies to every billing-cycle invoice until someone cancels it. Used for negotiated, ongoing rate reductions.

Stacking

What happens when more than one discount is active on the same target at once (for example two base-price discounts), set per-subscription via discountStackingMode. Discounts on different targets never compete: a base-price discount and a component discount both apply. A discount that loses under the stacking mode is not invoiced and does not use up any of its duration.

Combine (default)

All active discounts apply together. Fixed-amount discounts are subtracted first, then percentage discounts are applied to what remains.

Best wins

Only the single discount that saves the customer the most is applied, compared on each invoice; the rest sit idle while active. A tie goes to the one applied earliest.

First wins

Only the discount that was applied earliest takes effect.

Latest wins

Only the most recently applied discount takes effect — useful when a new promo should supersede an old one.

Amount and options

Every discount, whether from the library or one-off, can be shaped with these settings when you apply it.

Percentage or fixed

A percentage is a plain percent (10 means 10%) and works in any currency. A fixed amount is in the subscription’s currency. A library discount with a fixed amount is only available where it defines a value for that currency; on any other currency it cannot be applied.

Fixed mode (components)

For a fixed amount on a component: per unit (the default) takes the amount off each unit’s rate, so $2 off on 5 units is $10 off; flat lump sum takes the amount once off the whole line. A base-price discount has no units, so the setting does not apply there.

Unit limit (components)

Discount at most this many of the billed units, for example 20% off 3 of 15 seats. Leave it empty to discount every unit. A limit at or above the billed quantity changes nothing.

End date

An optional calendar date. The discount stops applying to invoices whose service period starts on or after it, whichever comes first, the date or the duration.

Adjustment invoices

Whether mid-cycle adjustment invoices are discounted too. On by default.

Reason

Required. Recorded in the Discount History with who applied it.

Discounts never take a line below zero: a fixed amount larger than what is left just consumes the rest. A discount takes effect from the next invoice generated; invoices already issued are not rewritten. You can later overwrite an active instance’s value, duration or options on that subscription only, which leaves the library definition and other subscriptions alone, or cancel it, which is prospective.

Where it applies

Invoice generation runs the normal pricing chain first — Custom Pricing Agreement resolution, scope walk, included-quantity netting — and produces line items exactly as it would with no discounts at all. Only then are active discount instances applied, strictly last, against the target they were attached to (base price, one Variable Component, or the whole invoice). A whole-invoice discount is applied last of all, to every line after the base-price and component discounts have taken their share, one-time fees included. The base-price lines of a multi-module plan, and the per-tier lines of a graduated Variable Component, are each discounted as one target and the result is shared back across the lines, so a fixed amount comes off once, not once per line. The pre-discount amount and each discount’s contribution are preserved on the invoice line so a customer’s bill always shows what changed and why.

Order of discounting

Pricing chain resolves
Agreement, scope walk, included-quantity netting.
Lines are built
Same lines as with no discounts at all.
Base and component discounts
Each target is discounted as one group across its lines.
Whole-invoice discount
Last of all, every line including one-time fees.

Discounts never touch the resolved rate; they apply after it, whole-invoice last.

By default, a discount also reduces mid-cycle adjustment invoices — expansions and overage invoices. Turn off its applyToAdjustments flag to limit a discount to standard start and renewal invoices; adjustment invoices are then left at full price. Either way only start and renewal invoices use up a counted duration.

Lifecycle on renewal

A counted instance (first invoice only, or a fixed number) only advances its applied-renewal counter, and only auto-expires, after the invoice it discounted has actually been generated and persisted — never speculatively. This keeps a failed or retried invoice run from burning down a customer’s remaining discounted renewals. Every apply, cancel, expiry, and the renewal that consumes a count is written to an immutable Discount History log, separate from the general Lifecycle Event log.

Previewing before you commit

Because the math is a pure function of (resolved price, active instances, stacking mode), Revvly can show the effect of a discount before it is ever applied to a real invoice. The dashboard’s discount preview walks the same calculation used at billing time and shows the pre-discount amount, each discount’s deduction, and the final amount per target — so you can see next month’s bill before saving anything.