Descontos

​

O que são Códigos de Desconto?

• Descontos flexíveis: Percentual ou valor fixo de desconto
• Controle direcionado: Restringir por produto e ciclos de assinatura
• Governança de campanha: Datas de expiração e limites de uso
• Checkout sem interrupções: Suporte a campo de UI e API via sessões de checkout
• Descontos flexíveis: Descontos baseados em porcentagem ou em valor fixo
• Códigos combináveis: Aplique até 20 códigos por checkout, pagamento ou assinatura
• Controle direcionado: Restrinja por produto, ciclos de assinatura e elegibilidade do cliente
• Governança de campanhas: Datas de início programadas, datas de expiração e limites gerais e por cliente para uso
• Preços por moeda: Defina a dedução fixa, o limite do valor e o subtotal mínimo por moeda

​

Configuração do Painel

​

Configuração no Dashboard

• Nome do desconto (obrigatório): Rótulo interno para o Dashboard.
• Código (obrigatório): A sequência que os clientes inserem no checkout. Gere um código aleatório ou insira o seu próprio (mínimo de 3 caracteres, convertido automaticamente para letras maiúsculas).
• Tipo (obrigatório): Porcentagem (um percentual de desconto) ou Valor (uma dedução fixa).
• Valor (obrigatório): Para porcentagem, o percentual de desconto no Dashboard (por exemplo, 15 para 15%). Pela API, o mesmo valor é informado em pontos-base (1500). Para valor, a dedução fixa na moeda padrão do código.
• Data de início (opcional): Programe o código para ser ativado em uma data futura. Deixe em branco para ativá-lo imediatamente.
• Data de expiração (opcional): Data após a qual o código não poderá mais ser resgatado.
• Limite de uso (opcional, em Avançado): Número máximo total de resgates entre todos os clientes.
• Limite de uso por cliente (opcional, em Avançado): Número máximo de resgates por qualquer cliente individual. Deve ser menor ou igual ao limite geral de uso quando ambos forem definidos.
• Elegibilidade do cliente (opcional): Restrinja quem pode resgatar — todos os clientes, clientes de primeira compra, clientes existentes ou uma lista selecionada manualmente.
• Opções de moeda (opcional): O valor do desconto para cada moeda em que você vende. Consulte Opções por moeda.
• Restrição de produto (opcional): Limite o código a produtos específicos.
• Limite de ciclos da assinatura (opcional, em Avançado): Número de ciclos de cobrança aos quais o desconto se aplica. Deixe em branco para aplicação indefinida.
• Preservar na alteração do plano (opcional): Mantenha o desconto ativo quando uma assinatura mudar de plano (preserve_on_plan_change).
• Metadados (opcional): Anexe pares chave–valor personalizados para controle interno.
• Exigir um valor mínimo do pedido (opcional, em Avançado): Subtotal mínimo do carrinho (por moeda) para que o código seja aplicado.

​

Tipos de desconto

​

Elegibilidade do cliente

​

Opções por moeda

• Valor — para um desconto do tipo Valor, a dedução fixa nessa moeda; para um desconto do tipo Porcentagem, o limite máximo do desconto. Corresponde a max_amount_possible na API.
• Padrão — marque uma moeda como padrão. As moedas não configuradas são convertidas a partir dessa moeda padrão.

• Subtotal mínimo — o código só será aplicado quando o carrinho atingir esse subtotal nessa moeda. 0 significa que não há mínimo.

​

Experiência de checkout

​

Combinação de códigos de desconto

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  discount_codes: ['WELCOME10', 'BLACKFRIDAY20'], // applied in this order
  customer: { email: 'user@example.com' },
  return_url: 'https://yoursite.com/return'
});

​

Gerenciamento pela API

​

Casos de uso comuns

• Ofertas introdutórias: promoções de lançamento por tempo limitado para novos produtos
• Volume ou B2B: descontos contratados para conjuntos de produtos selecionados
• Ações de retenção: códigos de recuperação em fluxos de prevenção de churn
• Campanhas sazonais: promoções baseadas em feriados ou eventos

​

Exemplos de integração

​

Criar um desconto com metadados

const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500, // 15%
  code: 'SUMMER2025',
  metadata: {
    campaign: 'summer_promo',
    source: 'email_blast'
  }
});

​

Aplicar descontos em Checkout Sessions

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  discount_codes: ['BLACKFRIDAY2024', 'NEWUSER5'], // stacked in array order
  customer: { email: 'user@example.com', name: 'Jane Doe' },
  return_url: 'https://yoursite.com/return'
});

​

Aplicar descontos durante alterações de plano

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20']
});

​

Ocultar o campo do código de desconto

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  feature_flags: {
    allow_discount_code: false
  },
  return_url: 'https://yoursite.com/return'
});

​

Práticas recomendadas

• Dê nomes claros: Use códigos reconhecíveis que correspondam aos nomes das campanhas.
• Defina um prazo: Adicione datas de expiração para criar urgência e evitar uso indevido.
• Defina o escopo com cuidado: Limite a produtos específicos para evitar perda de margem.
• Valide antecipadamente: Verifique a aplicabilidade do código antes de confirmar o checkout.
• Monitore o impacto: Acompanhe o uso e a conversão por campanha.