Skip to main content
This walkthrough configures a percent discount on a line item, with a per-period cap and a lifetime cap, and checks the result against a few months of usage.

​
Step 1: Decide the percentage

Pick the flat percentage to take off the gross bill amount on this line item. For this walkthrough, we’ll use 20%.

​
Step 2: Decide whether you need a per-period cap

A per-period cap limits how much discount can apply within a single cadence window (or billing period, if no cadence is set). Use this if you want to bound the dollar value of the discount regardless of how large the bill gets within a period. For this walkthrough, set:
  • value: 20 (20%)
  • max_per_period: 500 ($500 cap)
  • cadence: leave unset, so the cap applies per billing period

​
Step 3: Decide whether you need a lifetime cap

A lifetime cap limits the cumulative dollar discount across the entire contract. Once it’s exhausted, the discount stops permanently — there’s no partial application after that point. Add:
  • max_lifetime: 5000 ($5,000 cumulative cap)

​
Step 4: Add a label

Set a label for how this discount should appear on the customer’s invoice line, for example “Loyalty discount.”

​
Step 5: Set the order, if stacking with other discounts

If this line item has other discounts configured too, set the order field to control the sequence they apply in. The recommended order across discount types is quantity discount first, then fixed discount, then percent discount.

​
Step 6: Save and preview

Save the line item configuration, then use invoice preview to confirm the numbers. Walking through a few months of usage against the configuration above: 
Month 1: Bill=$4,000. 20%=$800, capped at $500 per-period cap. Lifetime used: $500. Invoice: $3,500.
Month 2: Bill=$1,500. 20%=$300, under the cap. Lifetime used: $800. Invoice: $1,200.
...
Month 10: Bill=$3,000. 20%=$600, capped at $500, but only $200 of lifetime cap remains. Invoice: $2,800.
Month 11: Lifetime cap exhausted. Full price applies.

​
What’s next

  • To see how this interacts with quantity discounts and pricing models, see the percent discount concepts doc.
  • To configure a quantity discount or volume pricing on the same line item, see those docs.