Descontos recorrentes

Além dos descontos pontuais aplicados a uma fatura, um contrato pode ter descontos recorrentes — que se repetem automaticamente nas próximas faturas, pela quantidade de faturas definida.

O que é

Um desconto recorrente é um acordo de desconto que vive no contrato, não em uma fatura isolada. A partir do ciclo de início, a Aira aplica o desconto às próximas faturas que cobram o alvo, até completar a quantidade contratada — 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

Vigência

Todo desconto recorrente tem uma data de início (alinhada aos ciclos do contrato) e, opcionalmente, uma quantidade de faturas (invoiceCount). A partir do início, o desconto se aplica às próximas invoiceCount faturas que cobram o alvo — em contratos com cobrança antecipada, a fatura de ativação conta como a primeira. Sem quantidade definida (null), 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 imediatamente às faturas ainda abertas que estejam dentro da quantidade contratada.

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`	inteiro ≥ 1	Centavos quando `fixed`; basis points quando `percentage`, até `10000` (100%) — acima disso a API responde `400` na validação do corpo
`description`	string	Texto do desconto exibido nas faturas
`startDate`	data (`YYYY-MM-DD`)	Ciclo em que o desconto começa — deve coincidir com uma data de ciclo do contrato
`invoiceCount`	inteiro ≥ 1 ou `null`	Quantidade de faturas que recebem o desconto, contadas a partir do início; `null` = sem fim
`distributionMode`	`proportional`, `full`	Distribuição em faturas com split (ver acima). Padrão: `proportional`
`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",
  "invoiceCount": null,
  "distributionMode": "proportional",
  "isActive": true
}

Na resposta, isActive indica se o desconto está valendo: enquanto ativo, ele é aplicado às próximas faturas até completar a quantidade; ao ser desativado, permanece no histórico e as faturas seguintes não o recebem.

O contrato precisa estar ativo. Para alterar valor ou alvo de um desconto recorrente, 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 pro rata
Ciclo de vida — os status do contrato

​O que é

​Tipo de desconto

​Onde o desconto incide

​Vigência

​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

Vigência

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