Understanding and Troubleshooting Coupon Redemptions in Recurly

Coupons are a core tool for offering discounts and promotions in Recurly. They can be applied to subscriptions, one-time charges, or invoices depending on how they’re configured. When something is misconfigured, merchants often see issues like:

• “The coupon is valid but not applying to the subscription.”
• “The coupon works in sandbox but not in production.”
• “The discount is smaller than expected.”

This article explains how coupon redemptions work, the most common reasons a coupon fails to apply, and a step-by-step approach to diagnosing and fixing issues.

How Coupons Work in Recurly

A coupon in Recurly defines rules for:

• Discount type: fixed-amount vs. percent-based.
• Duration: one-time, single term, or forever.
• Applies to: plans, plan families, or all items.
• Redemption limits: per account and global usage limits.
• Validity window: start and end dates.
• Currency: which currencies are supported for multi-currency sites.

Where Coupons Can Be Applied

• At signup: On the checkout page, Hosted Payment Pages, or via API when creating a subscription or purchase.
• On existing accounts: Through the Admin UI or API for an existing subscription or invoice.
• Programmatically: Using Recurly.js or v3 API during subscription lifecycle events.

Common Reasons a Coupon Is Not Applied

The majority of “coupon not working” issues fall into one of these categories:

Troubleshooting Steps

Step 1: Confirm the Coupon Status

1. Go to Configuration → Coupons in the Admin UI.
2. Open the coupon and confirm:
   • The coupon is Active, not archived.
   • Today’s date is within the coupon’s validity window.
   • The coupon has not exceeded its global redemption limit.

Step 2: Verify Plan & Currency Restrictions

1. Check the coupon’s Applies To section:
   • If restricted to specific plans, confirm the subscription plan code is listed.
   • If restricted to a plan family, ensure the subscription’s plan belongs to that family.
2. Verify the coupon supports the subscription’s currency:
   • For fixed-amount coupons, confirm a price is configured for the currency.
   • For percentage coupons, confirm the currency is enabled (if applicable).

Step 3: Check Account-Specific Limits

1. Open the customer’s account in Recurly.
2. Review the Coupons or Redemptions section:
   • Has this coupon already been redeemed on this account?
   • Is the coupon configured to only allow one redemption per account?
3. If the coupon has a per-account limit and it has been reached, Recurly will reject additional redemptions.

Step 4: Reproduce Using a Minimal Test Case

1. Create a new test account in Sandbox.
2. Create a subscription or one-time invoice using only:
   • One plan (or item) you know is eligible for the coupon.
   • The intended currency.
   • The coupon code entered exactly as configured.
3. If the coupon applies in this simple scenario, the issue is likely with:
   • A specific plan or add-on on the original account
   • Account-level limits or prior redemptions
   • Integration-level logic (e.g., API or checkout form)

Step 5: Review Logs & Integrations

• If using Hosted Payment Pages or Recurly.js, confirm the coupon field is being passed correctly.
• If using the API, verify the request body contains the correct coupon fields (examples below).
• If an integration (e.g., a custom checkout or CRM) is applying the coupon, inspect its logs or payloads.

API & UI Examples

Example: Creating a Subscription with a Coupon (v3)

# POST /subscriptions
curl -X POST "https://v3.recurly.com/subscriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/vnd.recurly.v2021-02-25" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_code": "basic-monthly",
    "currency": "USD",
    "account": {
      "code": "acct_1001",
      "email": "user@example.com"
    },
    "coupon_codes": ["WELCOME10"]
  }'
    

In this example, Recurly will validate:

• That WELCOME10 exists and is active.
• That it applies to basic-monthly.
• That it supports the USD currency.
• That the account has not exceeded per-account redemption limits.

Example: Applying a Coupon to an Existing Account (v3)

# POST /accounts/{account_id}/coupon_redemptions
curl -X POST "https://v3.recurly.com/accounts/acct_1001/coupon_redemptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/vnd.recurly.v2021-02-25" \
  -H "Content-Type: application/json" \
  -d '{
    "coupon_code": "WELCOME10"
  }'
    

This associates the coupon with the account so that eligible invoices and subscriptions for that account receive the discount according to the coupon rules.

Admin UI Example: Applying a Coupon

1. Navigate to the customer’s Account page.
2. Click Add Coupon (or equivalent action depending on your UI version).
3. Enter the coupon code exactly as configured.
4. Save. Review the upcoming or newly generated invoice to confirm the discount is applied.

Best Practices

• Test in Sandbox first: Always validate new coupons with test accounts and subscriptions before going live.
• Use clear naming conventions: Include plan or campaign identifiers in the coupon code (e.g., Q4-TRIAL-20OFF).
• Document restrictions: Clearly note plan, currency, and duration restrictions in internal documentation.
• Avoid overlapping campaigns: Limit multiple active coupons that target the same audience and plans to reduce confusion.
• Monitor usage: Periodically review coupon redemptions and expiration dates so customers aren’t surprised when a promotion ends.
• Coordinate with accounting: Ensure finance teams understand which invoices are discounted and why, especially for long-running promotions.

FAQ

Why does the coupon show on the account but not on the invoice?

Most commonly, the invoice line items are not eligible for the coupon (wrong plan, wrong currency, or one-time charges that are excluded). Confirm the coupon’s Applies To settings and the invoice’s line items.

Can a customer have multiple coupons at the same time?

Depending on configuration, an account may have multiple coupon redemptions, but they will not always stack on the same invoice. Recurly enforces stacking rules based on coupon configuration and billing rules.

Do coupons apply to past invoices?

No. Coupons typically apply to future invoices. Applying a coupon to an account or subscription after an invoice has been issued will not retroactively update that invoice. You may need to issue a credit or refund if a discount should have been applied historically.

Why does the discount amount look smaller than expected?

Confirm whether the coupon is configured to apply to:

• Only recurring charges (not setup fees or add-ons),
• Only specific plans,
• Pre-tax or post-tax amounts, depending on your configuration.

Resources

• Recurly API v3 Generate a Coupon Redemption
• Recurly API v3 Creating a Subscription
• Coupons and Discounts