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 R50,00eoprodutocustarR 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: { ... }
// }
- 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
});
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 |
