How Coupon Scope and Discount Behavior Work in Recurly

Coupon-related concerns often come down to one core issue: the coupon was configured for a different scope than the merchant expected. 

Why a coupon may not apply

• The coupon is restricted to specific items, plans, or redemption conditions that are not present in the purchase request.
• The merchant expects the coupon to work on one-time charges, but the coupon was configured for a different billing scenario.
• The coupon is valid generally, but not for the specific line items being previewed or purchased.
• The coupon has already been redeemed or is limited in a way that prevents the current use.

Item-specific coupons for one-time charges

If you want a coupon to apply only to a defined set of items, the items in the purchase flow must line up with the coupon's configured scope. In practice, this means the eligible item codes and the purchase payload must agree with each other.

If a purchase preview does not show the coupon applying, the first thing to check is whether the preview request contains the exact items the coupon is meant to discount.

One-time discounts for a single customer

Merchants sometimes want a coupon that effectively behaves like an account-specific one-time exception. The safest pattern is usually to create a tightly controlled coupon that matches the intended use case, such as a short validity window, limited redemption count, or a specific checkout flow.

In other words, treat the one-time discount as a controlled redemption event rather than assuming a coupon becomes permanently attached to the customer account.

Why discounts can appear to stack or repeat

When a merchant reports an unexpected extra discount, it is usually worth checking whether more than one discount source is active at the same time. Common examples include:

• a coupon plus an existing subscription or plan discount
• multiple redemptions or repeated test attempts against the same scenario
• item-specific discount logic interacting with broader purchase-level expectations

If the final pricing looks wrong, compare the expected discount source with every discount that may already exist on the subscription, account, or purchase payload.

What to check before opening a support case

• The coupon code and intended redemption rules
• Whether the coupon is supposed to apply to a subscription, a one-time charge, or both
• The exact item or plan codes in the purchase request
• Whether the coupon is limited by date, redemption count, or scope
• Whether another discount is already being applied

Best practices

• Design coupon rules around the exact billing scenario you want to support.
• Test with purchase preview before moving to production flows.
• Keep item-specific coupon rules as explicit as possible.
• Avoid using one coupon to represent many different discount behaviors.
• When troubleshooting, isolate one discount source at a time.