Pular para o conteúdo
Criar conta
ou
Entrar
O logotipo da documentação da Stripe
/
Pergunte à IA
Criar conta
Login
Comece já
Pagamentos
Receita
Plataformas e marketplaces
Gestão de valores
Ferramentas para desenvolvedores
Visão geral
Billing
    Visão geral
    Sobre as APIs do Billing
    Assinaturas
      Como funcionam as assinaturas
      Início rápido
      Casos de uso
      Crie sua integração
      Recursos de assinatura
        Faturas de assinatura
        Cronogramas de assinatura
        Preços de assinatura
        Modelos de preço recorrente
        Incorporar uma tabela de preços
        Iniciar assinaturas
        Definir quantidades
        Defina ciclos de faturamento
        Inicie assinaturas com data passada
        Inscrever-se em vários itens
        Definir períodos de avaliação
        Aplicar cupons
          Scripts de desconto personalizados
        Migrar assinaturas para a Stripe
        Como cobranças proporcionais de crédito são calculadas
        Pagamentos de assinaturas
        Formas de pagamento de assinaturas
        Integrar com processamento de pagamentos externo
        Métodos de cobrança
        Compartilhe um link para atualizar dados de pagamento
        SCA (autenticação forte de cliente)
        Gerenciar assinaturas
        Modifique assinaturas
        Gerencie atualizações pendentes
      Análises
    Invoicing
    Cobrança por uso
    Connect e Billing
    Tax e Billing
    Cotações
    Recuperação de receitas
    Automações
    Scripts
    Reconhecimento de receitas
    Gerenciamento de clientes
    Direitos
    Teste sua integração
Tributos
Relatórios
Dados
Incorporação de startups
Página inicialReceitaBillingSubscriptionsSubscription features

Cupons e códigos promocionais

Adicione descontos a assinaturas e itens de assinatura usando cupons e códigos promocionais.

Copiar página

Resgate cupons para aplicar descontos às assinaturas oferecidas. Você também pode usar cupons para criar códigos promocionais para compartilhar com seus clientes. Os clientes podem resgatar esses códigos promocionais para aplicar descontos às assinaturas.

  • Cupons: você cria e gerencia cupons para definir descontos, como uma porcentagem ou um valor de desconto do preço da assinatura.
  • Códigos promocionais: você cria códigos voltados para o cliente que mapeiam seus cupons. Por exemplo, FALLPROMO e SPRINGPROMO podem mapear para um único cupom de 25% de desconto. Você pode compartilhar códigos promocionais diretamente com seus clientes, que podem inseri-los e resgatá-los no checkout.

Você pode usar cupons e códigos promocionais para:

  • Aplicar um ou mais descontos a uma fatura, assinatura ou item de assinatura
  • Aplique um ou mais descontos por um determinado período
  • Reduzir uma porcentagem ou um valor fixo das faturas

Você também pode definir um cupom que um cliente deve resgatar até uma data específica ou que está limitado a um número definido de resgates para todos os seus clientes.

Para usar descontos em pagamentos avulsos, consulte Adicionar descontos a pagamentos avulsos.

Cupons

Para aplicar descontos a um cliente ou cobranças de um cliente, resgate cupons em descontos. Saiba como criar e gerenciar cupons nas seções a seguir.

Criar um cupom

Crie cupons no Dashboard ou com a API:

Command Line
cURL
curl https://api.stripe.com/v1/coupons \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d duration=once \ -d id=free-period \ -d percent_off=100

A tabela a seguir contém parâmetros de cupom.

ConfiguraçãoDescrição
idUm identificador exclusivo para o cupom.
percent_off ou amount_offO valor retirado do subtotal pela duração do cupom.
currency (se amount_off estiver definido)O código ISO de três letras para a moeda do valor a ser decolado.
currency_options (se amount_off estiver definido) optionalSe você vende em várias moedas, o valor deve ser retirado do subtotal para moedas diferentes. Os cupons multimoedas seguem as mesmas regras dos preços multimoedas.
durationIndica a validade do cupom. Os valores incluem uma vez, vitalício ou repetido.
max_redemptions optionalO número máximo de vezes que um cupom pode ser resgatado em todos os clientes.
redeem_by optionalA última data em que você pode aplicar este cupom aos clientes.
applies_to optionalLimita os itens em uma fatura aos quais o cupom pode ser aplicado.

Só é possível editar o nome do cupom após a criação.

Definir produtos qualificados

Para definir os produtos elegíveis para descontos, adicione os IDs de produto relevantes ao hash applies_to no cupom. Esta lista de produtos qualificados também se aplica aos códigos promocionais associados ao cupom.

Se você configurar um cupom para aplicar a produtos específicos e uma assinatura não tiver nenhum produto aplicável, nenhum desconto será aplicado quando você adicionar o cupom à assinatura.

Quando você altera uma assinatura, todos os descontos existentes são aplicados durante o cálculo da cobrança proporcional. Não é possível aplicar mais descontos proporcionais aos itens de linha na fatura gerada.

Aplique cupons a assinaturas

Depois de criar cupons, aplique-os a uma assinatura para criar um desconto. Você pode aplicar o cupom durante a criação da assinatura ou atualizando a assinatura existente de um cliente.

Command Line
cURL
curl https://api.stripe.com/v1/subscriptions \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d customer=
{{CUSTOMER_ID}}
\ -d "items[0][price]"=
{{PRICE_ID}}
\ -d "discounts[0][coupon]"=free-period

Você ainda pode criar uma assinatura quando o cliente não tiver uma forma de pagamento armazenada se não for necessário fazer nenhum pagamento imediato após a aplicação de cupons a ela.

Aplicar cupons ao Checkout

Aplique cupons a assinaturas em uma sessão do Checkout definindo o parâmetro discounts na API. Para criar uma sessão com desconto aplicado, passe o ID do cupom no parâmetro coupon da matriz discounts.

Command Line
curl
curl https://api.stripe.com/v1/checkout/sessions \ -u
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:
\ -d "payment_method_types[]"=card \ -d "line_items[][price]"=
{{PRICE_ID}}
\ -d "line_items[][quantity]"=1 \ -d mode=subscription \ -d "discounts[][coupon]"="{{COUPON_ID}}" \ -d success_url="https://example.com/success" \ -d cancel_url="https://example.com/cancel"

Excluir cupons

Você pode excluir cupons com o Dashboard ou a API.

A exclusão de um cupom impede que ele seja aplicado a assinaturas ou faturas futuras, mas não remove o desconto de nenhuma assinatura ou fatura que já o tenha.

Command Line
cURL
curl -X DELETE https://api.stripe.com/v1/coupons/free-period \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Duração do cupom

A duração de um cupom indica a validade do desconto resgatado. Por exemplo, um cupom de 50% de desconto com duração de 4 meses se aplica a todas as faturas no período de 4 meses, a partir da primeira aplicação do cupom. Se um cliente aplicar este cupom a uma assinatura anual durante o período de 4 meses do cupom, o desconto de 50% se aplicará a toda a assinatura anual. Em uma assinatura mensal, o cupom se aplica aos primeiros 4 meses. Para uma assinatura semanal, o cupom é aplicado a todas as faturas nos primeiros 4 meses.

Se estiver configurando a duração de um cupom na API, quando usar o valor repeating, é preciso especificar duration_in_months como o número de meses aos quais o cupom se aplica repetidamente. Se você definir a duração como once, o cupom será aplicado somente à primeira fatura. Se você definir a duração como forever, o cupom se aplica a todas as faturas indefinidamente.

Limites de resgate

Os limites de resgate se aplicam ao cupom para todos os clientes. Por exemplo, se você limitar a 50 o número de vezes que um cupom pode ser resgatado, poderá aplicá-lo aos seus clientes apenas 50 vezes. Isso pode ser uma vez para 50 clientes diferentes, um cliente 50 vezes ou vários clientes várias vezes até o máximo de 50 vezes.

Se você definir um cupom com durabilidade vitalícia quando um cliente usá-lo, mas o cupom tiver uma data de validade, todos os clientes que receberem esse cupom terão o desconto vitalício. Nenhum novo cliente poderá aplicar o cupom após a data de validade.

Códigos promocionais

Os códigos promocionais são destinados aos clientes que você cria para cupons. Por exemplo, FALLPROMO e SPRINGPROMO podem apontar para um único cupom de 25% de desconto. Você pode compartilhar códigos promocionais diretamente com seus clientes para usar no checkout.

Se você implementou o portal do cliente e ativou os códigos promocionais, os clientes podem aplicar um desconto ao fazer upgrade ou downgrade de suas assinaturas existentes no portal.

Cuidado

As assinaturas aplicam o código promocional e as atualizações de preço separadamente, o que pode causar atualizações inesperadas. Por exemplo, uma falha no pagamento pode causar falha no upgrade de preço, mas o código promocional incluído com a atualização de preço é bem-sucedido.

Personalize controles e limites de códigos promocionais especificando clientes elegíveis, primeiros pedidos de clientes, valores mínimos de pedidos, datas de validade e limites de resgate.

Restrições

Há algumas restrições aos códigos promocionais.

  • Não é possível aplicar um código promocional com restrição de valor em:
    • Objetos Subscription Item
    • Objetos Invoice Item
    • Objetos Subscriptions ao fazer uma atualização
    • Fases futuras em objetos Subscription Schedule

Criar códigos promocionais

O code não diferencia maiúsculas de minúsculas e é exclusivo dentre todos os códigos de promoção ativos para qualquer cliente. Por exemplo:

  • Você pode criar vários códigos promocionais restritos a determinados clientes usando o mesmo code, mas não pode reutilizar esse code em uma promoção que pode ser resgatada por qualquer cliente.
  • Se você criar um código promocional que pode ser resgatado por qualquer cliente, não é possível criar outro código promocional ativo com o mesmo code.
  • Você pode criar um código promocional com code: NEWUSER, inativá-lo com o parâmetro active: false e então criar um novo código promocional com code: NEWUSER.

Para criar um código promocional, especifique um coupon existente e as restrições aplicáveis (por exemplo, limitado a um customer específico). Se você tiver um código específico que deseja atribuir ao cliente (por exemplo, FALL25OFF), defina o code. Se você deixar esse campo em branco, a Stripe irá gerar um code aleatório para você.

Command Line
cURL
curl https://api.stripe.com/v1/promotion_codes \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d coupon=ZQO00CcH \ -d code=ALICE20 \ -d customer=
{{CUSTOMER_ID}}

Quando você cria um código promocional, ele herda a configuração do cupom associado.

Configurações de códigos promocionais

Ao definir as configurações do código promocional, é possível personalizar o seguinte:

  • Quais clientes podem usar um código promocional
  • Quantas vezes um cliente pode resgatar um código promocional
  • Quando um código promocional expira
  • Definir um valor mínimo para o qual um código promocional pode ser aplicado

Limitar por cliente

Para limitar um código promocional a um cliente específico, especifique um customer na criação do código promocional. Se você não especificar um cliente, qualquer cliente poderá resgatar o código promocional.

Limitar ao primeiro pedido

Limite o código promocional a novos clientes com o parâmetro first_time_transaction do atributo restrictions. Se o customer não for definido ou se um customer definido ainda não tiver feito nenhum pagamento nem tiver nenhuma fatura não nula, a transação será considerada a primeira transação.

Definir um valor mínimo

Com códigos promocionais, você pode definir um valor mínimo de transação para aplicação do desconto configurando as propriedades minimum_amount e minimum_amount_currency. Como as restrições por código promocional são verificadas no momento do resgate, o valor mínimo da transação se aplica somente ao pagamento inicial de uma assinatura. Se você vende em várias moedas, defina o valor mínimo de transação para moedas diferentes configurando a propriedade currency_options.

Personalizar validades

Defina uma data de validade no código promocional usando expires_at. Se o cupom correspondente já tiver a configuração redeem_by, a data de validade do código promocional não pode ser posterior à do cupom. Se promotion_code[expires_at] não for especificado, a redeem_by do cupom preencherá automaticamente expires_at.

  • Por exemplo, você planeja aceitar um cupom por um ano, mas quer que ele seja resgatado pelo cliente em até uma semana após o recebimento. O parâmetro coupon[redeem_by] deve ser daqui a um ano, e cada promotion_code[expires_at] deve ser uma semana após a criação.

Limitar resgates

Limite o número de resgates usando max_redemptions, que funciona de forma semelhante à dos cupons. Se o cupom correspondente já tiver a configuração max_redemptions, o max_redemptions do código promocional não pode ser maior do que o do cupom.

Desativar códigos promocionais

Defina se um código promocional pode ser resgatado atualmente com o parâmetro active. Contudo, se o cupom correspondente de um código promocional ficar inválido, todos os seus códigos promocionais são permanentemente desativados. Da mesma forma, se um código promocional atingir seu max_redemptions ou expires_at, ele se tornará permanentemente inativo. Esses códigos promocionais não podem ser reativados.

Aplicar códigos promocionais a assinaturas

Depois de criar um código promocional, resgate um desconto aplicando o código promocional a uma assinatura. Você pode aplicar códigos promocionais de duas maneiras:

  • Quando você cria uma assinatura
  • Quando você atualiza a assinatura existente de um cliente
  1. Liste os códigos promocionais e use o código do seu cliente como filtro para recuperar o ID do código promocional.
  2. Para aplicar o código promocional, use o ID do código promocional na chamada da API a seguir:
Command Line
cURL
curl https://api.stripe.com/v1/subscriptions \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d customer=
{{CUSTOMER_ID}}
\ -d "items[0][price]"=
{{PRICE_ID}}
\ -d "discounts[0][promotion_code]"=
{{PROMOTION_CODE_ID}}

Adição de códigos promocionais ao Checkout

Habilite códigos promocionais com a API definindo o parâmetro allow_promotion_codes nas sessões do Checkout. Quando allow_promotion_codes está ativado em uma sessão do Checkout, o Checkout inclui uma caixa de resgate de código promocional para uso pelos clientes.

Campo de código promocional no checkout

Campo de código promocional no checkout

Cupons empilháveis e códigos promocionais

Você pode adicionar vários cupons, códigos promocionais ou descontos resgatados à lista de cobranças de um cliente. Isso pode ser feito ao criar uma assinatura ou atualizando a assinatura existente de um cliente.

Aceitamos vários descontos em assinaturas e itens de assinatura.

Quando você cria uma assinatura com descontos cumulativos, cada desconto se aplica a todos os itens da assinatura. A ordem dos descontos é importante se você usar amount_off e percent_off. Por exemplo, os seguintes descontos acumulados se aplicam de forma diferente:

  • 20% de desconto depois US$ 5 de desconto
  • US$ 5 de desconto depois 20% de desconto
Command Line
cURL
curl https://api.stripe.com/v1/subscriptions \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d customer=
{{CUSTOMER_ID}}
\ -d "items[0][price]"=
{{PRICE_ID}}
\ -d "items[0][discounts][0][coupon]"=item-coupon \ -d "items[0][discounts][1][promotion_code]"=item-promo \ -d "discounts[0][coupon]"=sub-coupon \ -d "discounts[1][promotion_code]"=sub-promo

Restrições

Há algumas restrições ao uso de vários descontos.

  • Você pode configurar até 20 entradas no parâmetro discounts.
  • Cada entrada em discounts tem de ser única.
  • Não é possível passar um cupom e um código promocional criado a partir do mesmo cupom.
  • Não é possível passar um cupom e um desconto que é gerado a partir do mesmo cupom.
  • Os descontos resgatados já devem estar vinculados ao cliente ou assinatura que você está atualizando.

Atualizar uma assinatura

Você não precisa definir discounts se não pretende fazer alterações nos descontos existentes.

Ao atualizar discounts, você precisa passar qualquer coupon, promotion_code ou discount definido anteriormente que você deseja manter na assinatura.

Passe discounts = "" para eliminar todos os descontos da assinatura. Quando uma assinatura não tem descontos, o desconto por cliente, se houver, se aplica às faturas.

Se você já definiu mais de um desconto em uma assinatura com o novo parâmetro discounts, não é possível atualizar a assinatura com o parâmetro coupon ou promotion_code obsoleto. Da mesma forma, não é possível atualizar as fases de um cronograma com o parâmetro coupon ou promotion_code obsoleto se tiver definido mais de um desconto em uma fase anterior.

A atualização de discounts não incorre em cobranças proporcionais nem gera uma fatura isolada. Os novos descontos são aplicados na próxima vez que a assinatura criar uma fatura.

Métodos de desconto alternativos

Embora os cupons sejam a maneira mais comum de aplicar um desconto a uma assinatura, você também pode utilizar o seguinte:

  • Adicione um saldo do cliente negativo ao cliente.
  • Adicione itens de fatura negativos.
  • Adicione um segundo preço que seja uma versão mais barata do preço normal de um produto.

Desses métodos, os itens de fatura negativos fornecem informações mais detalhadas sobre qual desconto foi criado, quando e por quê.

Veja também

  • Alterar assinaturas
  • Trabalhar com faturas
  • API de cupons
  • API de códigos promocionais
Esta página foi útil?
SimNão
Precisa de ajuda? Fale com o suporte.
Participe do nosso programa de acesso antecipado.
Confira nosso changelog.
Dúvidas? Fale com a equipe de vendas.
LLM? Read llms.txt.
Powered by Markdoc