# Validar Cupom
`POST /v1/coupons/validate`
**Área:** Cupons

Endpoint público, sem autenticação — pensado para ser chamado do frontend do próprio cliente para validar um código de cupom antes de aplicá-lo numa cobrança ou checkout.

Sempre responde 200. Quando o cupom não é válido, valid=false e reason traz o motivo (COUPON_NOT_FOUND, COUPON_INACTIVE, COUPON_NOT_STARTED, COUPON_EXPIRED, COUPON_EXHAUSTED, MIN_AMOUNT_NOT_MET, PRODUCT_NOT_ELIGIBLE, COUPON_NOT_APPLICABLE, COUPON_ALREADY_USED).

Quando válido, devolve os dados do cupom necessários para calcular o efeito no checkout: para discountType=PERCENTAGE ou FIXED, use discountValue (e maxDiscount) para calcular o desconto. Para discountType=EXTRA_PERIOD, não há desconto a aplicar no valor — mostre uma mensagem como "+N dia(s)/mês(es) grátis" e deixe o efeito para a próxima cobrança.

### Request body

```json
{
  "code": "BEMVINDO10",
  "amount": 199.90,
  "productIds": ["price_1788364755079_psuecwgdc"],
  "chargeType": "RECURRING",
  "customerDocument": "12345678901"
}
```

### Campos do body

**Obrigatórios:** `code`

| Campo | Descrição |
|---|---|
| `code` | Código digitado pelo cliente |

**Opcionais**

| Campo | Descrição |
|---|---|
| `amount` | Valor do pedido, usado para checar minAmount e calcular o desconto |
| `productIds` | Price IDs do pedido, usados para checar restrição de produto |
| `chargeType` | Tipo da cobrança sendo montada (default RECURRING) (valores: RECURRING, ONE_TIME) |
| `customerDocument` | CPF/CNPJ do cliente, usado para checar firstTimeOnly |

### Resposta 200: 200 válido

```json
{
  "valid": true,
  "coupon": {
    "code": "BEMVINDO10",
    "name": "Cupom de boas-vindas",
    "description": "10% na primeira cobrança",
    "discountType": "PERCENTAGE",
    "discountValue": 10,
    "maxCycles": 3,
    "maxDiscount": 30.0,
    "validUntil": "2026-12-31T23:59:59.000Z",
    "appliesTo": "RECURRING",
    "firstTimeOnly": true
  }
}
```

### Resposta 200: 200 inválido

```json
{
  "valid": false,
  "reason": "COUPON_EXPIRED"
}
```

---
Página: https://docs.validapay.com.br/referencia/post-validar-cupom
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json