{
  "object": "doc",
  "title": "Find coupons: GET /api/v1/coupons",
  "description": "Active coupon codes and automatic promotions with 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 coupon codes and automatic promotions, filterable by retailer, category or product, each with its redemption success rate, sample size, terms and expiry. Costs 1 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=target\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\": \"target\",\n  \"retailer_name\": \"Target\",\n  \"code\": \"CIRCLE20KIT\",\n  \"requires_code\": true,\n  \"kind\": \"percent\",\n  \"value\": 20,\n  \"value_unit\": \"percent\",\n  \"title\": \"Target Circle 20% off one kitchen item\",\n  \"terms\": \"Requires a Target Circle account. Must be activated in the app 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."
}