# Listar Cupons
`GET /v1/coupons`
**Área:** Cupons

**Scopes necessários:** `products/read`

Lista os cupons cadastrados na conta, com paginação e filtros por status e busca por nome/código.

### Query parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `lastKey` | **sim** | base64 - optional |
| `status` | **sim** | ACTIVE \| PAUSED \| INACTIVE - optional |
| `search` | **sim** | busca por nome ou código - optional |
| `limit` | não | Quantidade de itens por página (default 50) - optional |

### Resposta 200: 200

```json
{
  "items": [
    {
      "couponId": "coup_1789157079333_fq358baak",
      "accountId": "4231833",
      "code": "BEMVINDO10",
      "name": "Cupom de boas-vindas",
      "description": "10% na primeira cobrança",
      "discountType": "PERCENTAGE",
      "discountValue": 10,
      "extraPeriodUnit": null,
      "maxCycles": 3,
      "maxRedemptions": 100,
      "currentRedemptions": 12,
      "minAmount": 50.0,
      "maxDiscount": 30.0,
      "validFrom": "2026-09-01T00:00:00.000Z",
      "validUntil": "2026-12-31T23:59:59.000Z",
      "productIds": [
        "price_1788364755079_psuecwgdc"
      ],
      "firstTimeOnly": true,
      "appliesTo": "RECURRING",
      "status": "ACTIVE",
      "createdAt": "2026-09-01T10:00:00.000Z",
      "updatedAt": "2026-09-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "totalPages": 1,
    "limit": 50,
    "hasMore": false,
    "lastKey": null
  }
}
```

---
Página: https://docs.validapay.com.br/referencia/get-listar-cupons
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json