> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Descontos

> Crie e gerencie cupons de desconto fixos ou percentuais para seus checkouts.

## Visão Geral

A Chargefy permite criar descontos que podem ser aplicados em checkouts para reduzir o valor da compra. Os descontos funcionam como cupons e podem ser do tipo **fixo** (valor em reais) ou **percentual**.

## Tipos de Desconto

### Desconto Fixo

Reduz um valor absoluto do total da compra, em centavos.

```typescript theme={null}
const discount = await chargefy.discounts.create({
  name: "Desconto de Boas-Vindas",
  code: "BEMVINDO50",
  type: "fixed",
  amount: 5000,        // R$ 50,00 (em centavos)
  currency: "brl",
  organization_id: "org_xxx"
});
```

> [!NOTE]
>
> O valor de desconto fixo nunca ultrapassa o total da compra. Se o desconto for de R$ 50,00 e o produto custar R$ 30,00, o desconto aplicado será de R\$ 30,00.

### Desconto Percentual

Reduz uma porcentagem do total da compra, usando **basis points** (pontos base).

```typescript theme={null}
const discount = await chargefy.discounts.create({
  name: "Black Friday 25%",
  code: "BLACK25",
  type: "percentage",
  basis_points: 2500,  // 25.00%
  organization_id: "org_xxx"
});
```

> [!NOTE]
>
> **Basis points**: 100 basis points = 1%. Então 2500 = 25%, 1050 = 10.5%, 500 = 5%.

## Duração do Desconto

Para assinaturas, você pode configurar por quanto tempo o desconto se aplica:

| Duração | Comportamento |
| - | - |
| `once` | Aplica apenas na primeira cobrança |
| `forever` | Aplica em todas as cobranças futuras |
| `repeating` | Aplica por um número definido de meses (`duration_in_months`) |

```typescript theme={null}
// Desconto que dura 3 meses na assinatura
const discount = await chargefy.discounts.create({
  name: "3 Meses com Desconto",
  code: "PROMO3M",
  type: "percentage",
  basis_points: 2000,  // 20%
  duration: "repeating",
  duration_in_months: 3,
  organization_id: "org_xxx"
});
```

## Limites de Uso

Você pode configurar limites para controlar quantas vezes um desconto pode ser utilizado:

```typescript theme={null}
const discount = await chargefy.discounts.create({
  name: "Promoção Limitada",
  code: "LIMITADO100",
  type: "fixed",
  amount: 2000,
  currency: "brl",
  max_redemptions: 100,  // Máximo de 100 usos
  starts_at: "2026-03-01T00:00:00Z",
  ends_at: "2026-03-31T23:59:59Z",
  organization_id: "org_xxx"
});
```

| Parâmetro | Descrição |
| - | - |
| `max_redemptions` | Número máximo de vezes que o desconto pode ser usado |
| `starts_at` | Data de início da validade |
| `ends_at` | Data de fim da validade |

## Validar e Resgatar

### Validar Código

Antes de aplicar um desconto, valide o código para verificar se ainda é válido:

```typescript theme={null}
const validation = await chargefy.discounts.validate({
  code: "BEMVINDO50",
  amount: 10000,  // Valor original em centavos
  organization_id: "org_xxx"
});

// Retorna:
// {
//   valid: true,
//   discount_amount: 5000,
//   final_amount: 5000,
//   discount: { ... }
// }
```

A validação verifica:

* Se o código existe e não foi deletado
* Se está dentro do período de validade (`starts_at` / `ends_at`)
* Se não atingiu o limite máximo de usos (`max_redemptions`)

### Resgatar Desconto

O resgate é feito **atomicamente** para evitar condições de corrida:

```typescript theme={null}
const redemption = await chargefy.discounts.redeem({
  discount_id: "disc_xxx",
  checkout_id: "checkout_xxx"
});
```

> [!NOTE]
>
> A operação de resgate utiliza uma função atômica no PostgreSQL para garantir que o limite de usos (`max_redemptions`) seja respeitado mesmo com múltiplas requisições simultâneas.

## Aplicar no Checkout

Descontos podem ser aplicados durante a criação do checkout:

```typescript theme={null}
const checkout = await chargefy.checkouts.create({
  product_price_id: "price_xxx",
  discount_id: "disc_xxx",
  // ... outros campos
});
```

Ou informando o código do desconto:

```typescript theme={null}
const checkout = await chargefy.checkouts.create({
  product_price_id: "price_xxx",
  discount_code: "BEMVINDO50",
  // ... outros campos
});
```

## Estatísticas

Consulte as estatísticas de uso de um desconto:

```typescript theme={null}
const stats = await chargefy.discounts.getStats(discountId);

// {
//   total_redemptions: 47,
//   total_discount_amount: 235000  // R$ 2.350,00 total concedido
// }
```

## Restrições de Edição

Após o primeiro uso de um desconto, alguns campos ficam **bloqueados para edição**:

| Campo | Editável após uso? |
| - | - |
| `name` | Sim |
| `code` | Sim |
| `max_redemptions` | Sim |
| `starts_at` / `ends_at` | Sim |
| `type` | **Não** |
| `amount` / `basis_points` | **Não** |
| `duration` | **Não** |

## Escopos de API

| Escopo | Permissão |
| - | - |
| `discounts:read` | Listar e visualizar descontos |
| `discounts:write` | Criar, atualizar e deletar descontos |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.