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
404error when using the direct path, you'll need to switch to the plan-scoped path. -
Double-check for any typos in your
plan_codeandcoupon_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_codein 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.
Comments
0 comments
Article is closed for comments.