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

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

Cria um cupom de desconto ou de período extra.

Um cupom PERCENTAGE ou FIXED desconta valor da cobrança. Um cupom EXTRA_PERIOD soma dias ou meses à data da próxima cobrança da assinatura, sem gerar cobrança no período pulado — por exemplo, um cupom de "1 mês grátis" numa assinatura mensal faz a próxima cobrança ocorrer 2 meses depois da anterior, em vez de 1.

O campo maxCycles controla em quantos ciclos recorrentes o benefício se repete: com maxCycles=3, os 3 próximos ciclos recebem o desconto (ou o período extra); a partir do 4º, a cobrança volta ao normal. Deixe vazio para o cupom valer em todos os ciclos, até a assinatura ser cancelada.

EXTRA_PERIOD exige appliesTo=RECURRING — não se aplica a cobranças avulsas.

Case de uso:

_Como SaaS, quero oferecer "2 meses grátis" para quem assina um plano anual, sem mexer no valor cobrado em cada ciclo._

### Request body

```json
{
  "code": "BEMVINDO10",
  "name": "Cupom de boas-vindas",
  "description": "10% na primeira cobrança",
  "discountType": "PERCENTAGE",
  "discountValue": 10,
  "extraPeriodUnit": "MONTHS",
  "maxCycles": 3,
  "maxRedemptions": 100,
  "minAmount": 50.00,
  "maxDiscount": 30.00,
  "validFrom": "2026-09-01T00:00:00.000Z",
  "validUntil": "2026-12-31T23:59:59.000Z",
  "productIds": ["price_1788364755079_psuecwgdc"],
  "firstTimeOnly": true,
  "appliesTo": "RECURRING"
}
```

### Campos do body

**Obrigatórios:** `code`, `discountType`, `discountValue`

| Campo | Descrição |
|---|---|
| `code` | Código que o cliente digita no checkout para aplicar o cupom (salvo em maiúsculas) |
| `discountType` | PERCENTAGE desconta % do valor, FIXED desconta um valor fixo em reais, EXTRA_PERIOD soma dias/meses à próxima cobrança em vez de descontar valor (valores: PERCENTAGE, FIXED, EXTRA_PERIOD) |
| `discountValue` | Percentual (0.01 a 100) para PERCENTAGE, valor em reais para FIXED, quantidade inteira de dias/meses para EXTRA_PERIOD (mín.: 0.01) |

**Opcionais**

| Campo | Descrição |
|---|---|
| `name` | Nome para identificação interna (default = code) |
| `description` |  |
| `extraPeriodUnit` | Obrigatório apenas quando discountType=EXTRA_PERIOD; unidade da quantidade em discountValue (valores: DAYS, MONTHS) |
| `maxCycles` | Quantos ciclos recorrentes recebem o benefício (desconto ou período extra); vazio = todos os ciclos, até a assinatura ser cancelada (mín.: 1) |
| `maxRedemptions` | Quantas vezes este código pode ser usado no total, somando todos os clientes; vazio = ilimitado (mín.: 1) |
| `minAmount` | Valor mínimo do pedido para o cupom ser aceito; sem efeito em EXTRA_PERIOD (mín.: 0.01) |
| `maxDiscount` | Teto do desconto em reais, útil para limitar cupons PERCENTAGE; sem efeito em FIXED ou EXTRA_PERIOD (mín.: 0.01) |
| `validFrom` | Cupom só é válido a partir desta data; vazio = válido imediatamente (formato: date-time) |
| `validUntil` | Cupom deixa de ser aceito após esta data; vazio = sem expiração (formato: date-time) |
| `productIds` | Restringe o cupom a price IDs específicos; vazio = todos os produtos |
| `firstTimeOnly` | Cada cliente (por CPF/CNPJ) só pode usar este cupom uma vez (default false) |
| `appliesTo` | Tipo de cobrança em que o cupom é aceito; EXTRA_PERIOD exige RECURRING (default ALL) (valores: ALL, RECURRING, ONE_TIME) |

### Resposta 201: 201

```json
{
  "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"
}
```

### Resposta 400: 400

```json
{
        "error": {
                "message": "Dados inválidos",
                "code": "VALIDATION_ERROR",
                "details": null,
                "timestamp": "2026-09-11T21:00:00.000Z"
        }
}
```

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