# Cupons

Os cupons permitem que você ofereça descontos aos seus clientes durante o checkout. Você pode criar cupons baseados em porcentagem ou em valor fixo que se aplicam ao pedido inteiro, a um produto específico ou ao custo de frete. Cada cupom possui um código único que os clientes inserem no checkout para receber o desconto.

O Capyshop suporta três tipos de desconto:

| Tipo de Desconto      | O Que É Descontado                                         |
| --------------------- | ---------------------------------------------------------- |
| **Order Discount**    | Reduz o subtotal do pedido (antes do frete e dos impostos) |
| **Product Discount**  | Reduz o preço de um produto específico no carrinho         |
| **Shipping Discount** | Reduz o custo de frete                                     |

## Navegando pelos seus cupons

Abra **Coupons** na barra lateral do admin para ver a lista completa. A tabela exibe o código, nome, tipo, valor do desconto, número de usos, status e um menu de ações de cada cupom.

![Lista de cupons](/features/coupons/coupons-list.png)

| Coluna   | Descrição                                                                             |
| -------- | ------------------------------------------------------------------------------------- |
| Code     | O código único do cupom (clique para editar)                                          |
| Name     | Nome de exibição do cupom                                                             |
| Type     | Um dos seguintes: Order Discount, Product Discount ou Shipping Discount               |
| Discount | O valor do desconto exibido como porcentagem (ex.: 46%) ou valor fixo (ex.: R$ 40,30) |
| Uses     | Quantas vezes o cupom foi utilizado                                                   |
| Status   | **Active**, **Inactive** ou **Expired**                                               |
| Actions  | Menu suspenso com as opções Edit e Delete                                             |

Você pode **ordenar** clicando no cabeçalho de qualquer coluna, **pesquisar** digitando na barra de busca e **filtrar** por status (All, Active, Inactive, Expired) usando o botão **Filter**.

### Ações em lote

Selecione múltiplos cupons usando as caixas de seleção para exibir os botões de ação em lote:

- **Activate** — ativa os cupons selecionados
- **Deactivate** — desativa os cupons selecionados
- **Delete** — remove permanentemente os cupons selecionados (com confirmação)

## Criando um cupom

Clique em **New Coupon** na página de listagem para abrir o formulário de criação.

![Criar cupom](/features/coupons/create-coupon.png)

### Detalhes do cupom

| Campo  | Obrigatório | Descrição                                                                                                                                           |
| ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name   | Sim         | Um nome de exibição para o cupom (ex.: "Summer Sale")                                                                                               |
| Code   | Sim         | O código que os clientes inserirão no checkout. Convertido automaticamente para maiúsculas. Não diferencia maiúsculas de minúsculas ao ser aplicado |
| Active | Não         | Alterne para ativar ou desativar o cupom. Somente cupons ativos podem ser aplicados no checkout                                                     |

### Configuração de regras

| Campo                | Obrigatório | Descrição                                                                                                                  |
| -------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| Discount Type        | Sim         | Escolha entre Order Discount, Product Discount ou Shipping Discount                                                        |
| Value Type           | Sim         | Escolha entre Percentage (%) ou Fixed Amount                                                                               |
| Value                | Sim         | O valor do desconto (ex.: 20 para 20%, ou 10.00 para R$ 10,00 de desconto)                                                 |
| Product              | Condicional | Exibido apenas quando o Discount Type é Product Discount. Selecione o produto específico que deve estar no carrinho        |
| Usage Rule           | Sim         | **Multiple Use** (ilimitado), **Single Per Customer** (uma vez por cliente) ou **Single Overall** (um uso no total)        |
| Minimum Order Amount | Não         | O subtotal mínimo do pedido necessário para aplicar este cupom                                                             |
| Expiration Date      | Não         | O cupom se tornará automaticamente inválido após esta data                                                                 |
| Target Countries     | Não         | Restrinja este cupom a clientes com entrega em países específicos. Se deixado vazio, o cupom é válido para todos os países |

## Editando um cupom

Clique em qualquer código de cupom na lista (ou escolha **Edit** no menu suspenso de ações) para abrir o formulário de edição. Ele contém os mesmos campos do formulário de criação, preenchidos com os dados atuais.

![Editar cupom](/features/coupons/edit-coupon.png)

Clique em **Save Changes** quando terminar.

## Excluindo um cupom

Para excluir um cupom, clique no menu suspenso de ações na linha correspondente e selecione **Delete**. Um diálogo de confirmação será exibido antes que o cupom seja removido permanentemente.

## Como os cupons funcionam no checkout

Durante o checkout, os clientes podem inserir um código de cupom no campo **Coupon Code** no painel de resumo do pedido.

![Campo de cupom no checkout](/features/coupons/storefront-checkout-coupon.png)

### Validação

Quando um cliente insere um código de cupom, o sistema verifica os seguintes critérios antes de aplicá-lo:

1. O cupom deve estar **active**
2. O cupom **não deve estar expirado**
3. O pedido deve atender ao **valor mínimo do pedido** (se definido)
4. O país de entrega do cliente deve corresponder aos **países-alvo** do cupom (se definido)
5. Para cupons de **Product Discount**, o produto especificado deve estar no carrinho
6. O cupom deve passar pela verificação da **regra de uso**:
   - **Multiple Use** — sempre passa
   - **Single Per Customer** — o cliente não deve ter utilizado este cupom anteriormente
   - **Single Overall** — o cupom não deve ter sido utilizado por ninguém

Se alguma verificação falhar, o cliente verá uma mensagem de erro explicando por que o cupom não pode ser aplicado.

### Como os descontos são calculados

| Tipo de Desconto      | Porcentagem                      | Valor Fixo                                                               |
| --------------------- | -------------------------------- | ------------------------------------------------------------------------ |
| **Order Discount**    | Subtotal x (valor / 100)         | Valor fixo descontado do subtotal (limitado ao subtotal)                 |
| **Product Discount**  | Total do produto x (valor / 100) | Valor fixo descontado do total do produto (limitado ao total do produto) |
| **Shipping Discount** | Custo de frete x (valor / 100)   | Valor fixo descontado do frete (limitado ao custo de frete)              |

> **Importante:** Apenas um cupom pode ser aplicado por pedido. Os clientes podem remover um cupom e aplicar um diferente antes de concluir o pedido.

> **Dica:** Os códigos de cupom não diferenciam maiúsculas de minúsculas. Um cliente pode inserir "summer2024" ou "SUMMER2024" e ambos funcionarão para o código `SUMMER2024`.