# Cupões

> Códigos de desconto em porcentagem ou valor fixo, para a primeira cobrança, para sempre ou por N meses, com validade, limite de usos e produtos aplicáveis. Como o desconto entra no checkout e nas renovações, e as mensagens que o comprador pode ver.

Um **cupão** é um código que o comprador digita no pagamento para ganhar desconto: **LANCAMENTO20**, **BEMVINDO10**, **ALUNO2026**. Serve para lançamentos, parcerias, campanhas e para recuperar quem desistiu.

## Para que serve

| Comunidade | Cupão | O que faz |
|---|---|---|
| Escola online | `LANCAMENTO20` | 20% na primeira mensalidade do plano Aluno, até 100 usos |
| Coworking | `PARCEIRO30` | R$ 30 por mês nos 3 primeiros meses do plano Residente, só para o parceiro |
| SaaS | `ANUAL10` | 10% para sempre, só nas opções anuais |
| Evento | `GRUPO15` | 15% no ingresso, válido até a véspera |

## Como funciona

### Tipos

| Tipo | Desconto | Exemplo |
|---|---|---|
| **Percentual** | Uma porcentagem do valor | 20% de R$ 129 = R$ 25,80 |
| **Valor Fixo** | Um valor em reais, por pedido | R$ 30 de desconto |
| **Teste Grátis** | Dias extras de teste | +7 dias de teste |

### Duração (para subscrições)

| Duração | No ecrã | O desconto vale |
|---|---|---|
| **uma vez** | *Desconto aplicado apenas no primeiro pagamento* | Só na primeira cobrança |
| **para sempre** | *Desconto aplicado em todos os pagamentos* | Em todas as cobranças, inclusive renovações |
| **repetindo** | *Desconto aplicado por N meses* | Nas N primeiras cobranças |

Num produto vendido uma vez, a duração não faz diferença: a cobrança é uma só.

### Limites

| Campo | Para quê |
|---|---|
| **Data de Início** \* | A partir de quando o código vale |
| **Data de Fim** | Até quando. Em branco, não expira |
| **Máximo de Utilizações** | Quantas vezes o código pode ser usado no total. Em branco, ilimitado |
| **Máximo por Utilizador** | Quantas vezes a mesma pessoa pode usar |
| **Produtos Aplicáveis** | Em quais produtos e opções vale. Vazio: em todos |

Pela API, um cupão aceita ainda: valor mínimo do pedido, desconto máximo, só na primeira compra na comunidade, só para subscrições, só para avulsos, produtos eliminados e se pode ser combinado com outro cupão.

### Como o desconto entra no pagamento

1. No checkout, o comprador clica em **Tenho um cupão**, digita o código e clica em **Aplicar**. O ecrã mostra *"Cupom LANCAMENTO20 aplicado · −R$ 25,80"* e a duração (*"Desconto só na primeira cobrança."*).
2. O desconto é calculado **antes da taxa**: a taxa da plataforma incide sobre o valor já com desconto.
3. Num pedido com plano e adicionais, um cupão de **valor fixo** é descontado **uma vez do pedido**, dividido entre os itens na proporção do valor de cada um; um **percentual** vale igual em cada item a que se aplica.
4. Nenhum item pode ficar abaixo de **R$ 1,00** depois do desconto.
5. O uso é registrado **quando o pagamento é confirmado**. Um pedido aberto (um boleto ainda não pago, por exemplo) segura um uso por até 7 dias.
6. Nas renovações, os cupões **para sempre** e **repetindo** continuam a valer pelo tempo combinado.
7. Com um [downsell](/monetizacao/downsell), primeiro entra o desconto do downsell, depois o do cupão.

O tipo **Teste Grátis** não é aceito no pagamento (*"Este tipo de cupom não pode ser usado no pagamento"*).

### Status

A lista mostra cada cupão com usos, validade e status:

| Status | Significa |
|---|---|
| **Ativo** | Vale |
| **Inativo** | Pausado por você |
| **Expirado** | Passou da data de término |
| **Esgotado** | Atingiu o máximo de usos |

### Quem pode

Criar, editar, pausar e eliminar: **proprietário** e **administrador**. O **financeiro** vê os cupões e o histórico de uso.

## Passo a passo: criar um cupão

*Papel: proprietário ou administrador.*

1. **Monetização › Cupões › Criar Cupão**.
2. **Código** \*: o que o cliente digita (ex.: `LANCAMENTO20`). Único na comunidade.
3. **Nome** \*: para a equipa (ex.: *Lançamento de março — 20%*).
4. **Tipo** \* e **Valor do Desconto** \*.
5. **Duração** \*: uma vez, para sempre ou repetindo (com os **Meses**).
6. **Data de Início** \* e, se quiser, **Data de Fim**.
7. **Máximo de Utilizações** e **Máximo por Utilizador**, se quiser limitar.
8. Em **Produtos Aplicáveis**, marque onde ele vale, ou deixe vazio para valer em tudo.
9. **Criar**.

![Criar Cupão](/screens/cupom-novo.png "Código, nome, tipo, valor, duração, validade, limites e produtos aplicáveis.")

Para pausar, mude o status para **Inativo**. Eliminar um cupão que já foi usado afeta os relatórios: o ecrã avisa quantas vezes ele foi usado.

## Exemplos com números

A taxa da plataforma é 6,99% + R$ 2,49 sobre o valor cobrado, já com o desconto.

**`LANCAMENTO20`: 20% uma vez, no Growth Mensal (R$ 129).**
Primeira mensalidade: R$ 129,00 − R$ 25,80 = **R$ 103,20**. Taxa: R$ 7,21 + R$ 2,49 = R$ 9,70. Ficam R$ 93,50. Da segunda em diante, R$ 129,00.

**`ANUAL10`: 10% para sempre, no Aluno Mensal (R$ 49).**
Todo mês: **R$ 44,10**. Taxa: R$ 3,08 + R$ 2,49 = R$ 5,57. Ficam R$ 38,53 por mês, enquanto a subscrição durar.

**`PARCEIRO30`: R$ 30 repetindo por 3 meses, no Residente (R$ 890).**
Meses 1 a 3: **R$ 860,00**. Do quarto em diante: R$ 890,00.

**R$ 50 de valor fixo num pedido de plano + adicional (R$ 129 + R$ 450 = R$ 579).**
O desconto é de R$ 50 no pedido, dividido na proporção: R$ 11,14 no plano e R$ 38,86 no adicional. Total: **R$ 529,00**.

**R$ 100 de valor fixo num plano de R$ 49.**
Recusado: o item ficaria abaixo de R$ 1,00.

## Boas práticas

- **Um código por campanha.** `INSTAGRAM20` e `NEWSLETTER20` com o mesmo desconto mostram de onde veio cada venda, pela coluna **Utilizações**.
- **Sempre com data de término** nas campanhas: um cupão esquecido vira desconto para sempre.
- **Máximo de Utilizações** em parcerias, para o código que vazou não virar a regra.
- **Prefira "uma vez" ou "repetindo"** a "para sempre": o "para sempre" reduz cada renovação enquanto a pessoa ficar.
- **Teste antes de divulgar**: aplique o código no checkout com uma conta de membro e confira o total.

## Mensagens que o comprador pode ver

| Mensagem | Por quê |
|---|---|
| *Código de cupão inválido* | O código não existe |
| *Cupão expirado* | Passou da data de término |
| *Cupão ainda não está válido* | Antes da data de início |
| *Este cupão não está ativo* | Está pausado |
| *Limite de uso do cupão foi atingido* | Esgotado |
| *Você já usou este cupão o número de vezes permitido* | Máximo por utilizador |
| *Este cupão não vale para este produto* | O produto não está nos aplicáveis |
| *Este cupão vale para pedidos a partir de R$ X* | Valor mínimo |
| *Este cupão vale só para a primeira compra nesta comunidade* | Restrição de primeira compra |
| *Com este cupão, um item ficaria abaixo de R$ 1,00, o mínimo que se pode cobrar* | Desconto maior que o preço |
| *Muitos códigos de cupão inválidos. Tente de novo em alguns minutos.* | 10 códigos recusados em 15 minutos |
| *O cupão deixou de valer e foi removido. Nada foi cobrado; confira o novo total e tente de novo.* | O cupão expirou ou esgotou entre aplicar e pagar |

## Erros comuns ao criar

| Mensagem | O que fazer |
|---|---|
| *Já existe um cupão com este código nesta comunidade* | Use outro código |
| *Informe por quantos meses o cupão recorrente vale* | Com **repetindo**, preencha os **Meses** |
| *Dias extras de teste só valem para cupão de teste grátis* | Tire os dias extras, ou mude o tipo |

## Perguntas frequentes

**O cupão vale na renovação?**
Os cupões **para sempre** e **repetindo**, sim, pelo tempo combinado. **Uma vez**, só na primeira cobrança.

**Dá para usar dois cupões?**
Só se os dois forem combináveis. Por padrão, um cupão por pedido.

**O cupão reduz a taxa da plataforma?**
A taxa é calculada sobre o valor com desconto: um desconto menor no preço é também uma taxa menor em reais.

**O membro pode usar cupão ao somar uma extensão depois, pelo Faturação?**
Não, por enquanto; o cupão vale na compra do plano e na oferta de última chance.

**Como sei quantas vezes um cupão foi usado?**
Na coluna **Utilizações** da lista, e no histórico de uso do cupão.

## Na API

`POST /api/coupons`, `PUT .../coupons/{id}`, `PATCH .../coupons/{id}/status`, `GET .../coupons/{id}/usage` e `POST .../coupons/validate` (`code`, `productId`, `amount`). No checkout, `couponCode` em `POST /api/checkout/calculate-price` e em `POST /api/checkout`. Ver [Coupons](/api/referencia/coupons).

## Relacionados

- [Downsell](/monetizacao/downsell)
- [Checkout](/pagamentos/checkout)
- [Taxa da plataforma](/pagamentos/taxa-da-plataforma)