# Find working coupons

Coupon discovery finds discount codes that actually work on a brand's store and reports how much each one takes off. It does not trust a code from a list. It applies each candidate to a live cart and keeps the ones the store accepts, the same way Honey or Coupert do.

```bash
curl "https://dev.ziffi.xyz/v1/coupons?brand=mcaffeine"
```

You can target by `product` (a product_uid or id), by `brand` (a slug), or by `domain` (a raw store host).

## The response

```json
{
  "data": {
    "brand": "mCaffeine",
    "host": "mcaffeine.com",
    "method": "graphql",
    "currency": "INR",
    "tested": 20,
    "applicable_count": 1,
    "best": { "code": "WELCOME10", "discount_minor": 3990, "kind": "percent" },
    "coupons": [
      { "code": "WELCOME10", "applicable": true, "discount_minor": 3990,
        "currency": "INR", "kind": "percent", "source": "pattern" }
    ]
  },
  "tier": "live"
}
```

`discount_minor` is what the code took off a single-item test cart, in minor units. `applicable` is the store's own truth: only codes the live cart accepts are reported.

## Kinds

`percent`, `fixed`, `free_shipping`, `auto` (a no-code automatic discount), or `unknown`.

## Important limit

Coupon discovery probes a live store cart, which requires a residential network path. It is available where that path is configured. Treat a `503` or an empty result as "not available from here" rather than "no coupons exist".

## Next steps

- [Get live price](#/price): combine with the live price for the landed cost.
- [Tiers and freshness](#/tiers): coupons are a live-tier feature.