Cupons e códigos promocionais

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:

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

Definir produtos qualificados

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.

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.

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.

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.

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

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

Limitar ao primeiro pedido

Definir um valor mínimo

Personalizar validades

Limitar resgates

Desativar códigos promocionais

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

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

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

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