{
  "object": "doc",
  "title": "Find coupons: GET /api/v1/coupons",
  "description": "Active retailer promotions with terms and success rates.",
  "section": "API reference",
  "url": "https://cart-route.com/docs/api/coupons",
  "updated": "2026-09-23",
  "prev": "https://cart-route.com/docs/api/price-history",
  "next": "https://cart-route.com/docs/api/reference",
  "text": "`GET /api/v1/coupons` lists active retailer promotions, filterable by retailer, category or product, each with its redemption success rate, sample size, terms and expiry. Costs 0 credit. Coupons that apply to a product are also embedded in every search and product offer.\n\nGET https://cart-route.com/api/v1/coupons?retailer=amazon\n\nCoupon verification is not connected for Amazon, Best Buy and eBay yet, so this endpoint currently returns an empty list and costs nothing. The retailer's own discount from its list price is in every offer as `list_price_usd` and `discount_from_list_pct`.\n\n## Which filters does it take?\n\n| Name | Type | Description |\n\n| `retailer` | string | Retailer id or slug. |\n\n| `category` | string | Category name. Returns category coupons and sitewide ones. |\n\n| `product` | string | Product id, slug, GTIN or MPN. Returns coupons that apply to it. |\n\n| `limit` | integer 1–100 | Default 50. Sorted by success rate, then sample size. |\n\n## What does a coupon look like?\n\n```\n{\n  \"coupon_id\": \"cpn_05pgl3b\",\n  \"retailer_id\": \"amazon\",\n  \"retailer_name\": \"Amazon\",\n  \"code\": null,\n  \"requires_code\": false,\n  \"kind\": \"percent\",\n  \"value\": 20,\n  \"value_unit\": \"percent\",\n  \"title\": \"20% off one kitchen item\",\n  \"terms\": \"Must be clipped on the product page before checkout.\",\n  \"min_spend_usd\": null,\n  \"applies_to\": \"category:Kitchen\",\n  \"stacks_with_sale\": true,\n  \"requires_eligibility\": false,\n  \"success_rate\": 0.68,\n  \"sample_size\": 3301,\n  \"last_verified_at\": \"2026-09-23T07:12:40.000Z\",\n  \"expires_at\": \"2026-09-30T10:12:40.000Z\",\n  \"source\": \"loyalty_program\"\n}\n```\n\n## What do the coupon fields mean?\n\n| Field | Meaning |\n\n| `code`, `requires_code` | The code to enter, or `null` when the promotion applies automatically. |\n\n| `kind` | `percent`, `amount` (USD off), `shipping` (free shipping) or `gift_card` (a perk; never subtracted from price). |\n\n| `applies_to` | `product`, `category:<name>` or `sitewide`. |\n\n| `min_spend_usd` | Minimum order value, or `null`. |\n\n| `requires_eligibility` | Student, education or similar. Listed, never assumed in `effective_price_usd`. |\n\n| `success_rate`, `sample_size` | Share of recent redemption attempts that applied, and how many attempts that is based on. |\n\n| `stacks_with_sale` | Whether it applies on top of a sale price. |\n\n| `last_verified_at`, `expires_at` | When it was last checked, and when it ends. Expired coupons never appear. |\n\n| `estimated_savings_usd` | Only inside an offer: the saving on that specific offer. |\n\n## How much should an agent trust a coupon?\n\nWeigh `success_rate` by `sample_size`: 0.9 over 2,000 attempts is dependable, 0.9 over 40 is a hint. Automatic promotions (`requires_code: false`) are the most reliable because the retailer applies them only when the cart qualifies. Tell the shopper about `terms` that need action, such as activating a loyalty offer."
}