How Do I Troubleshoot Coupon Retrieval Issues with Recurly.js? – Recurly

When using Recurly.js to look up coupons, a coupon that is restricted to a specific plan will return 404 Not Found if requested via the direct coupons endpoint (/js/v1/coupons/<coupon_code>). By design, plan-restricted coupons must be fetched with the plan-scoped path: /js/v1/plans/<plan_code>/coupons/<coupon_code>.

Last updated: 2025-08-14

Troubleshooting Coupon Retrieval with Recurly.js

If you're experiencing issues with coupon retrieval, follow these steps to diagnose the problem.

Step 1: Confirm the Coupon's Scope

First, confirm whether the coupon applies to all plans or is limited to specific plans. If it's plan-specific, you need to know the exact plan_code used in the subscription flow.

Step 2: Use the Correct API Path

The API path you use to fetch the coupon depends on its scope.

For a coupon that applies to all plans: Use the direct path below. GET https://api.recurly.com/js/v1/coupons/<coupon_code>?key=<public_js_key>
For a plan-specific coupon: You must use the plan-scoped path below. GET https://api.recurly.com/js/v1/plans/<plan_code>/coupons/<coupon_code>?key=<public_js_key>

Step 3: Handle Errors and Verify Details

If you're still having issues, check for the following common problems.

If a valid, plan-specific coupon returns a 404 error when using the direct path, you'll need to switch to the plan-scoped path.
Double-check for any typos in your plan_code and coupon_code.
Ensure you are using your public Recurly.js key for client-side lookups.

Examples

All-plan coupon (200)

GET https://api.recurly.com/js/v1/coupons/coop?key=ewr1-EXAMPLEPUBLICKEY

Plan-specific coupon queried directly (404)

GET https://api.recurly.com/js/v1/coupons/basic-coop?key=ewr1-EXAMPLEPUBLICKEY

HTTP/1.1 404 Not Found
{
  "error": {
    "code": "not-found",
    "message": "Could not find the requested ."
  }
}

Plan-specific coupon with plan code (200)

GET https://api.recurly.com/js/v1/plans/basic/coupons/basic-coop?key=ewr1-EXAMPLEPUBLICKEY

HTTP/1.1 200 OK
{
  "code": "basic-coop",
  "name": "Basic Plan Coupon",
  "applies_to_all_plans": false,
  "applies_to_plans": true,
  "plans": ["basic"],
  "discount": { "...": "..." },
  "redemption_resource": "subscription"
}

Best Practices

For coupons that are restricted to specific plans, it's important to use the correct lookup method to avoid errors. Here are a few best practices to ensure a smooth process:

For plan-restricted coupons, always include the correct plan_code in the lookup path.
A 404 from the direct coupons path for a plan-specific coupon is expected behavior.
Avoid caching negative lookups that are performed without a plan_code.