Descontos

​

O que são Códigos de Desconto?

• Campanhas sazonais: Black Friday, lançamentos de produtos ou aniversários
• Ofertas de aquisição: Incentivos para primeira compra ou recompensas de indicação
• Retenção: Recompensas de recuperação ou fidelidade para clientes existentes
• Negócios B2B: Preços contratados ou negociados via códigos privados

​

Principais Benefícios

• 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 — combine campanhas (por exemplo, WELCOME10 + BLACKFRIDAY20) sem criar códigos personalizados
• 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 de uso
• Preços por moeda: Defina a dedução fixa, o limite máximo e o subtotal mínimo por moeda
• Checkout integrado: Suporte a campo de UI e API por meio de sessões de checkout

​

Configuração do Painel

​

Configuração no painel

• Nome do desconto (obrigatório): Nome interno e nome exibido no painel
• Código (obrigatório): A sequência que os clientes inserem no checkout ou um código aleatório gerado usando o botão fornecido
• Tipo (obrigatório): Escolha Porcentagem (um percentual de desconto) ou Valor (uma dedução fixa)
• Valor (obrigatório): O valor percentual ou o valor fixo de um desconto do tipo Valor
• Data de início (opcional): Programe o código para se tornar ativo posteriormente; deixe vazio para ativá-lo imediatamente
• Data de expiração (opcional): Data após a qual o código se torna inválido
• Limite de uso (opcional): Máximo de resgates no total entre todos os clientes
• Limite de uso por cliente (opcional): 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 o código — todos os clientes, clientes de primeira compra, clientes existentes ou uma lista selecionada manualmente
• Opções de moeda (opcional): Valores por moeda — consulte Opções por moeda
• Restrição de produto (opcional): Limite a aplicabilidade a produtos selecionados
• Limite do ciclo de assinatura (opcional): Número de ciclos de cobrança aos quais o desconto se aplica
• Preservar na alteração do plano (opcional): Mantenha o desconto ativo quando o plano da assinatura mudar (preserve_on_plan_change)
• Metadata (opcional): Anexe pares personalizados de chave–valor para acompanhamento interno ou integrações

​

Tipos de desconto

​

Elegibilidade do cliente

​

Opções por moeda

• Valor — para um desconto do tipo Valor, esta é a própria dedução; para um desconto do tipo Porcentagem, limita quanto o código pode descontar. Corresponde a max_amount_possible na API.
• Subtotal mínimo — o código só se aplica quando o carrinho atinge esse subtotal. 0 significa que não há mínimo.
• Padrão — uma entrada pode ser marcada como padrão, para que outras moedas não configuradas sejam convertidas a partir dela.

​

Experiência de checkout

1. Os compradores inserem o código no campo de checkout.
2. Os descontos elegíveis são aplicados e os totais são atualizados imediatamente.

​

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
• Vendas em volume ou B2B: Descontos contratados para conjuntos de produtos selecionados
• Estratégias 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 metadata

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 de 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

• Nomeie claramente: Use códigos reconhecíveis que correspondam aos nomes das campanhas
• Defina um período: 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