Descontos recorrentes

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.

O que é

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”.

Tipo de desconto

Monetário
Percentual

Um valor fixo abatido a cada ciclo.Exemplo: R$ 200 de desconto por mês em um contrato mensal.

Onde o desconto incide

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

Janela de validade

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.

Distribuição em faturas com split

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.

Comportamento

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.

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 ou a emissão de uma nova fatura.

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

Gerenciar via API

Descontos recorrentes podem ser criados, listados e desativados pela API, autenticada por chave de API (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`

Campos do desconto recorrente

Campo	Valores	Descrição
`targetScope`	`invoice`, `plan`, `contract_minimum_amount`	Onde o desconto incide (ver Onde o desconto 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)
`planId`	UUID	Informe quando o `targetScope` for `plan`.

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

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"
  }'

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

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.

Próximos passos

Descontos e alocações — descontos pontuais e divisão de faturas
Configuração de cobrança — ciclos, períodos e prorrata
Ciclo de vida — os status do contrato

​O que é

​Tipo de desconto

​Onde o desconto incide

​Janela de validade

​Distribuição em faturas com split

​Comportamento

​Gerenciar via API

​Campos do desconto recorrente

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

​Próximos passos

O que é

Tipo de desconto

Onde o desconto incide

Janela de validade

Distribuição em faturas com split

Comportamento

Gerenciar via API

Campos do desconto recorrente

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

Próximos passos