> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plugtopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cupons

> Criação e gerenciamento de cupons de desconto para assinaturas.

## Criar cupom

`POST /api/v1/subscriptions/coupons` — requer `X-Client-ID` + `X-API-Key`.

```json theme={null}
{
  "code": "VERAO30",
  "name": "30% de desconto — Verão",
  "description": "Promoção de verão, primeiros 3 meses",
  "discount_type": "percentage",
  "discount_value": 30,
  "max_redemptions": 200,
  "max_cycles": 3,
  "valid_from": "2026-12-01",
  "valid_until": "2027-02-28"
}
```

| Campo             | Tipo                         | Obrigatório | Descrição                                                                    |
| ----------------- | ---------------------------- | ----------- | ---------------------------------------------------------------------------- |
| `code`            | string alfanumérico (max 50) | sim         | Código único por empresa. Convertido automaticamente para maiúsculas         |
| `name`            | string (max 255)             | sim         | Nome interno do cupom                                                        |
| `description`     | string (max 1000)            | não         | Descrição opcional                                                           |
| `discount_type`   | `percentage\|fixed`          | sim         | Tipo de desconto                                                             |
| `discount_value`  | inteiro                      | sim         | Para `percentage`: 1–100. Para `fixed`: valor em centavos                    |
| `max_redemptions` | inteiro (min 1)              | não         | Limite total de resgates. `null` = ilimitado                                 |
| `max_cycles`      | inteiro (min 1)              | não         | Aplica o desconto apenas nos primeiros N ciclos. `null` = aplica para sempre |
| `valid_from`      | date (`YYYY-MM-DD`)          | sim         | Data de início da validade                                                   |
| `valid_until`     | date após `valid_from`       | não         | Data de fim da validade. `null` = sem expiração                              |

**Resposta `201`:**

```json theme={null}
{
  "id": "019a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "code": "VERAO30",
  "name": "30% de desconto — Verão",
  "description": "Promoção de verão, primeiros 3 meses",
  "discount_type": "percentage",
  "discount_value": 30,
  "max_redemptions": 200,
  "redemptions_count": 0,
  "max_cycles": 3,
  "valid_from": "2026-12-01T00:00:00+00:00",
  "valid_until": "2027-02-28T23:59:59+00:00",
  "is_active": true,
  "created_at": "2026-06-25T12:00:00+00:00"
}
```

***

## Atualizar cupom

`PUT /api/v1/subscriptions/coupons/{uuid}` — requer `X-Client-ID` + `X-API-Key`.

Campos editáveis: `name`, `description`, `max_redemptions`, `max_cycles`, `valid_until`, `is_active`.

`code`, `discount_type` e `discount_value` são imutáveis após a criação.

***

## Listar e deletar cupons

| Método   | Rota                                   | Descrição             |
| -------- | -------------------------------------- | --------------------- |
| `GET`    | `/api/v1/subscriptions/coupons`        | Lista todos os cupons |
| `GET`    | `/api/v1/subscriptions/coupons/{uuid}` | Detalha um cupom      |
| `DELETE` | `/api/v1/subscriptions/coupons/{uuid}` | Soft-delete           |