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.

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"
});

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

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

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)

// 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:

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:

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:

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

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:

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

Ou informando o código do desconto:

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:

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