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

# Descontos recorrentes

> Configure descontos que se repetem a cada ciclo de um contrato, dentro de uma janela de datas.

> Além dos descontos pontuais aplicados a uma fatura, um contrato pode ter descontos recorrentes — que se repetem automaticamente a cada ciclo, dentro de uma janela de datas definida.

<h2 id="o-que-e">
  O que é
</h2>

Um desconto recorrente é um acordo de desconto que vive no **contrato**, não em uma fatura isolada. A cada ciclo de faturamento dentro da sua janela de validade, a Aira aplica o desconto à fatura gerada — sem necessidade de lançá-lo manualmente todo mês.

É a forma de modelar acordos do tipo "10% de desconto durante os 6 primeiros meses" ou "R\$ 200 de abatimento fixo enquanto o contrato durar".

<br />

<h2 id="tipo-de-desconto">
  Tipo de desconto
</h2>

<Tabs>
  <Tab title="Monetário">
    Um valor fixo abatido a cada ciclo.

    **Exemplo:** `R$ 200` de desconto por mês em um contrato mensal.
  </Tab>

  <Tab title="Percentual">
    Uma porcentagem abatida a cada ciclo, até 100%.

    **Exemplo:** 10% de desconto sobre cada fatura do contrato.
  </Tab>
</Tabs>

<br />

<h2 id="onde-incide">
  Onde o desconto incide
</h2>

Você define o alvo do desconto recorrente dentro do contrato:

| Alvo                        | O que abate                                        |
| --------------------------- | -------------------------------------------------- |
| Fatura inteira              | O total de cada fatura do contrato                 |
| Plano                       | Os itens de um plano específico do contrato        |
| Franquia mínima do contrato | O valor cobrado quando o uso fica abaixo do mínimo |

<br />

<h2 id="janela-de-validade">
  Janela de validade
</h2>

Todo desconto recorrente tem uma **data de início** e, opcionalmente, uma **data de término**, ambas alinhadas aos ciclos do contrato. O desconto se aplica apenas aos ciclos dentro dessa janela. Sem data de término, o desconto vale enquanto o contrato durar.

<br />

<h2 id="distribuicao-split">
  Distribuição em faturas com split
</h2>

Quando o contrato divide o valor entre múltiplos destinatários (split percentual), um desconto monetário recorrente pode ser distribuído de duas formas:

| Modo         | Comportamento                                                                            |
| ------------ | ---------------------------------------------------------------------------------------- |
| Proporcional | O valor do desconto é dividido entre as faturas do split, na mesma proporção da alocação |
| Cheio        | O valor integral do desconto é aplicado a cada fatura do split                           |

Descontos percentuais sempre incidem sobre o total de cada fatura, independentemente do split.

<br />

<h2 id="comportamento">
  Comportamento
</h2>

* O desconto recorrente só pode ser criado em um **contrato ativo**.
* Ao ser criado, ele se aplica **retroativamente às faturas ainda abertas** dentro da janela.

<Note>
  Descontos recorrentes não alteram **faturas já emitidas**. Uma fatura emitida está congelada — o desconto passa a valer dos ciclos abertos em diante. Para corrigir uma fatura já emitida, o caminho é um [desconto pontual](/faturas/descontos-e-alocacoes) ou a emissão de uma nova fatura.
</Note>

* Um desconto recorrente é **ativado ou desativado**, não editado. Para mudar valor ou alvo, desative o atual e crie um novo.

<br />

<h2 id="gerenciar-via-api">
  Gerenciar via API
</h2>

Descontos recorrentes podem ser criados, listados e desativados pela API, autenticada por [chave de API](/api-reference/autenticacao) (header `X-API-KEY`).

| Método | Endpoint                                                                          | Ação                                        | Permissão         |
| ------ | --------------------------------------------------------------------------------- | ------------------------------------------- | ----------------- |
| `POST` | `/v1/contracts/{id}/recurring-discounts`                                          | Criar um desconto recorrente                | `contracts:write` |
| `GET`  | `/v1/contracts/{id}/recurring-discounts`                                          | Listar os descontos recorrentes do contrato | `contracts:read`  |
| `POST` | `/v1/contracts/{id}/recurring-discounts/{contractRecurringDiscountId}/deactivate` | Desativar um desconto recorrente            | `contracts:write` |

<h3 id="campos-desconto-recorrente">
  Campos do desconto recorrente
</h3>

| Campo              | Valores                                      | Descrição                                                                  |
| ------------------ | -------------------------------------------- | -------------------------------------------------------------------------- |
| `targetScope`      | `invoice`, `plan`, `contract_minimum_amount` | Onde o desconto incide (ver [Onde o desconto incide](#onde-incide))        |
| `method`           | `fixed`, `percentage`                        | Valor fixo (em centavos) ou percentual (em *basis points*: `10000` = 100%) |
| `amount`           | número                                       | Centavos quando `fixed`; basis points (0–10000) quando `percentage`        |
| `description`      | string                                       | Texto do desconto                                                          |
| `startDate`        | data (`YYYY-MM-DD`)                          | Primeiro ciclo em que o desconto vale                                      |
| `endDate`          | data ou `null`                               | Último ciclo; `null` = sem fim                                             |
| `distributionMode` | `proportional`, `full`                       | Distribuição em faturas com split (ver [acima](#distribuicao-split))       |
| `planId`           | UUID                                         | Informe quando o `targetScope` for `plan`.                                 |

### Exemplo: 10% de desconto na fatura, a partir de maio

```bash theme={null}
curl -X POST https://api.useaira.com/v1/contracts/{id}/recurring-discounts \
  -H "X-API-KEY: sua_chave_api" \
  -H "Content-Type: application/json" \
  -d '{
    "targetScope": "invoice",
    "method": "percentage",
    "amount": 1000,
    "description": "Desconto de fidelidade",
    "startDate": "2026-05-01"
  }'
```

```json theme={null}
{
  "id": "e5f6a7b8-0000-0000-0000-000000000000",
  "planId": null,
  "targetScope": "invoice",
  "method": "percentage",
  "amount": 1000,
  "description": "Desconto de fidelidade",
  "startDate": "2026-05-01",
  "endDate": null,
  "distributionMode": "proportional",
  "isActive": true
}
```

<Note>
  O contrato precisa estar **ativo**. Não existe endpoint de edição de desconto recorrente: para alterar valor ou alvo, **desative** o atual e crie um novo.
</Note>

<br />

<h2 id="proximos-passos">
  Próximos passos
</h2>

* [Descontos e alocações](/faturas/descontos-e-alocacoes) — descontos pontuais e divisão de faturas
* [Configuração de cobrança](/contratos/configuracao-de-cobranca) — ciclos, períodos e prorrata
* [Ciclo de vida](/contratos/ciclo-de-vida) — os status do contrato