# Cupons e códigos promocionais Adicione descontos a assinaturas e itens de assinatura usando cupons e códigos promocionais. Crie e gerencie cupons e códigos promocionais para aplicar descontos às assinaturas, aos itens de assinatura ou às faturas de um cliente usando o Dashboard ou as APIs da Stripe. Use cupons para: - Aplicar [descontos](https://docs.stripe.com/api/discounts.md) a uma assinatura, a um item de assinatura ou a uma fatura - Configurar um cupom para ser aplicado uma vez, por um número definido de meses ou indefinidamente - Reduzir uma porcentagem ou um valor fixo das faturas ## Cupons versus códigos promocionais Estas são as diferenças entre um cupom e um código promocional: - [Cupons](https://docs.stripe.com/billing/subscriptions/coupons.md#coupons): você decide quem e quando um cliente recebe o desconto. São descontos orientados pelo backend (seu sistema decide quem recebe o desconto). - [Códigos promocionais](https://docs.stripe.com/billing/subscriptions/coupons.md#promotion-codes): seu cliente decide quando aplicar um desconto. Esse é um código voltado para o cliente que envolve um cupom, adicionando uma camada de distribuição e controle sobre os cupons. Muitos códigos promocionais podem fazer referência a um único cupom. Os códigos promocionais herdam as restrições de produtos de seu cupom pai. Por exemplo, se um cupom for aplicável apenas a determinados produtos, qualquer código promocional criado a partir dele terá as mesmas restrições. Nesta página, “desconto” tem dois significados. Na linguagem cotidiana, um desconto é qualquer redução de preço. Na API da Stripe, um [Discount](https://docs.stripe.com/api/discounts/object.md) é um objeto específico que representa a aplicação de um cupom a um cliente, assinatura ou fatura. Quando um cliente resgata um cupom, a Stripe cria um objeto `Discount` para acompanhar esse resgate. Você pode aplicar até 20 descontos a uma assinatura, a um item de assinatura ou a uma fatura. Esse limite é compartilhado entre cupons e códigos promocionais. | | **Cupom** | **Código promocional** | | --- | --- | --- | | Definição​ | Objeto da API que define a lógica de desconto. Aplique-o diretamente à assinatura de um cliente usando o Dashboard ou a API. | Código voltado para o cliente que faz referência aos seus cupons. Esta é a string que o cliente insere no checkout. Por exemplo, `FALLPROMO` e `SPRINGPROMO` podem fazer referência a um único cupom de 25% de desconto. | | Caso de uso | Sua equipe de vendas fecha um negócio com um cliente para um desconto negociado de 20% em sua assinatura anual. Seu backend aplica o desconto diretamente e o cliente nunca digita nada. | Sua equipe de marketing lança uma campanha em rede social e deseja que os criadores compartilhem o código `EXAMPLE2026` que dá aos novos assinantes 25% de desconto por 3 meses. Ele só funciona para novos clientes com um gasto mínimo de US$ 50,00 e você deseja limitá-lo a 500 resgates. | | Restringir a um cliente específico | ❌ Não aceito | ✓ Compatível | | Aplicar apenas à primeira compra | ❌ Não aceito | ✓ Compatível | | Gasto mínimo para resgatar | ❌ Não aceito | ✓ Compatível | | Desativar sem excluir | Só é possível excluir, e não desativar cupons. A exclusão não remove descontos existentes, mas impede novas aplicações. Excluir um cupom arquivará os códigos promocionais associados a ele. | Você pode arquivar o código promocional alternando a sinalização `active` | Para usar descontos em pagamentos únicos, consulte [Adicionar descontos para pagamentos únicos](https://docs.stripe.com/payments/checkout/discounts.md). ## Cupons Para reduzir as cobranças de um cliente, resgate um cupom para criar um objeto [Discount](https://docs.stripe.com/api/discounts/object.md) em uma assinatura ou em um cliente. Saiba como criar e gerenciar cupons nas seções a seguir. ### Criar um cupom Crie cupons no Dashboard ou usando o método [Create a Coupon](https://docs.stripe.com/api/coupons/create.md): #### Dashboard 1. No Dashboard, abra a página [Produtos](https://dashboard.stripe.com/test/products?active=true). 2. Clique em **Cupons**. 3. Clique em **+Novo**. 4. Na caixa de diálogo **Criar um cupom**, insira os parâmetros do cupom. 5. Clique em **Criar cupom**. A seguir estão todas as configurações para cupons. O nome é a única configuração que você poderá editar depois de criar o cupom. | Configuração | Descrição | | --- | --- | | **Nome** | O nome do cupom que aparece em recibos e faturas. | | **ID** (opcional) | Um identificador exclusivo para o cupom na API. Se você deixar esse campo em branco, a Stripe gera um ID para você. | | **Tipo** | Determina se um cupom desconta uma assinatura por um valor fixo ou por uma porcentagem. | | **Porcentual de desconto** ou **Valor do desconto** | Indica quanto o cupom realmente desconta. Se você vende em várias moedas, um único cupom pode definir diferentes valores de desconto para moedas diferentes. Os cupons multimoedas seguem as mesmas regras dos [preços multimoedas](https://docs.stripe.com/products-prices/how-products-and-prices-work.md#multiple-currencies). | | **Aplicar a produtos específicos** (opcional) | Limita os tipos de itens aos quais o cupom pode ser aplicado. | | **Duração** | Indica a validade do cupom. | | **Limites de resgate** (opcional) | Permite limitar quando um cliente pode resgatar o cupom e o número de vezes que ele pode ser resgatado. | | **Códigos** (opcional) | Permite criar [códigos promocionais](https://docs.stripe.com/billing/subscriptions/coupons.md#promotion-codes) para o cupom. | #### API ```curl curl https://api.stripe.com/v1/coupons \ -u "<>:" \ -d duration=once \ -d id=free-period \ -d percent_off=100 ``` A tabela a seguir contém parâmetros de cupom. | Configuração | Descrição | | --- | --- | | `id` | Um identificador exclusivo para o cupom. | | `percent_off` ou `amount_off` | O 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) (opcional) | Se 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](https://docs.stripe.com/products-prices/how-products-and-prices-work.md#multiple-currencies). | | `duration` | Indica a validade do cupom. Os valores incluem **uma vez**, **vitalício** ou **repetido**. | | `max_redemptions` (opcional) | O número máximo de vezes que um cupom pode ser resgatado em todos os clientes. | | `redeem_by` (opcional) | A última data em que você pode aplicar este cupom aos clientes. | | `applies_to` (opcional) | Limita os itens em uma fatura aos quais o cupom pode ser aplicado. | ### Definir produtos qualificados #### Dashboard Para definir os produtos elegíveis para descontos, adicione o produto relevante no campo **Aplicar a um produto específico**. Todos os códigos promocionais associados ao cupom também são restritos a essa lista de produtos elegíveis. 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. #### API 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ê [faz alterações](https://docs.stripe.com/billing/subscriptions/change.md) em um assinatura, a Stripe calcula o pro rata e aplica os descontos existentes. Não é possível descontar itens de linha pro rata 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](https://docs.stripe.com/api.md#update_subscription). #### Dashboard 1. No Dashboard, abra a página [Assinaturas](https://dashboard.stripe.com/test/subscriptions?status=active) página. 2. Clique na assinatura relevante. 3. Clique em **Ações**. 4. Clique em **Atualizar assinatura**. 5. Clique em **Adicionar cupom**. 6. Selecione um ou mais cupons nos menus suspensos e clique em **Enviar**. #### API > #### Use a API Accounts v2 para representar clientes > > A API Accounts v2 está geralmente disponível para usuários do Connect e em prévia pública para outros usuários da Stripe. Se faz parte da prévia de Accounts v2, é necessário [especificar uma versão de prévia](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) no seu código. > > Para participar da prévia de Accounts v2, acesse [Prévias e recursos da conta](https://dashboard.stripe.com/settings/previews) no Dashboard e ative **Formas de pagamento reutilizáveis para Global Payouts**. > > Para a maioria dos casos de uso, recomendamos [modelar seus clientes como objetos Accounts configuradas pelo cliente](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md), em vez de usar objetos [Customer](https://docs.stripe.com/api/customers.md). #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "discounts[0][coupon]=free-period" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "discounts[0][coupon]=free-period" ``` Ainda é possível criar um assinatura quando um cliente não tiver uma forma de pagamento armazenada se [nenhum pagamento imediato](https://docs.stripe.com/billing/subscriptions/deferred-payment.md) for obrigatório depois que você aplica cupons a ele. ### Aplicar cupons ao Checkout Aplique cupons a assinaturas em uma sessão do Checkout definindo o parâmetro `discounts` ao [criar uma Sessão do Checkout](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-discounts). Para criar uma sessão com um desconto aplicado, passe o ID do cupom no parâmetro `coupon` do array `discounts`. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -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" ``` ### Excluir cupons Você pode excluir cupons pelo Dashboard ou usando o [método Delete a Coupon](https://docs.stripe.com/api/coupons/delete.md). 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. #### Dashboard 1. No Dashboard, abra a página [Produtos](https://dashboard.stripe.com/test/products?active=true). 2. Clique em **Cupons** 3. Clique no cupom desejado. 4. Clique no menu de navegação (⋯). 5. Clique em **Excluir cupom**. #### API ```curl curl -X DELETE https://api.stripe.com/v1/coupons/free-period \ -u "<>:" ``` ### Duração do cupom A duração de um cupom indica por quanto tempo o [discount](https://docs.stripe.com/api/.md#discounts) resgatado é válido. Por padrão, a duração é `once`, que se aplica somente à primeira fatura. Defina `duration=repeating` com `duration_in_months` para aplicar um desconto por vários meses ou `duration=forever` para aplicá-lo a todas as faturas por tempo indeterminado. Por exemplo, um cupom com 50% de desconto e `duration_in_months=4` é aplicado a todas as faturas durante o período de 4 meses iniciado quando o cupom é aplicado pela primeira vez. Em uma assinatura mensal, o cupom é aplicado às 4 primeiras faturas. Em uma assinatura anual, o desconto de 50% é aplicado ao ano inteiro se a assinatura for renovada dentro do período de 4 meses. Em uma assinatura semanal, ele é aplicado a todas as faturas nos primeiros 4 meses. Quando uma assinatura usa um cupom com `duration=once`, o cupom é considerado utilizado depois que a fatura é finalizada e é removido da matriz `discounts` da assinatura: - Antes de o cupom ser aplicado a qualquer fatura, `discounts` da assinatura inclui o objeto de desconto. - Depois que a fatura é finalizada, `discounts` da assinatura não inclui mais esse desconto - A fatura que utilizou o cupom ainda mostra o desconto aplicado no recurso da fatura e nos itens da linha. Isso significa que uma assinatura pode parecer não ter nenhum desconto mesmo que um cupom tenha sido aplicado. > Se você aplicar um cupom a uma [assinatura retroativa](https://docs.stripe.com/billing/subscriptions/backdating.md), a duração do cupom começa a ser contabilizada a partir da data de início retroativa, e não a partir de quando você faz a chamada da API. Para cupons `recorrentes`, isso significa que o período retroativo consome parte da duração do cupom. O `duration_in_months` do cupom deve ser maior que o período retroativo se você quiser que o desconto seja aplicado às faturas após o período retroativo. Consulte [Retroatividade e descontos](https://docs.stripe.com/billing/subscriptions/backdating.md#backdating-discounts) para mais detalhes. ### Limites de resgate Aplicar um cupom significa vinculá-lo diretamente a uma assinatura, cliente ou fatura usando a API ou o Dashboard. Resgatar um código promocional significa que o cliente insere um código no checkout para ativar o cupom associado. Ambas as ações contam para o mesmo limite `max_redemptions` do cupom. Os limites de resgate determinam quantas vezes um cupom pode ser aplicado entre todos os clientes. Por exemplo, definir `max_redemptions=50` significa que o cupom pode ser aplicado no máximo 50 vezes no total: uma vez para 50 clientes diferentes, 50 vezes para o mesmo cliente ou qualquer combinação até que o limite seja atingido. Ao usar códigos promocionais, o resgate do código por um cliente conta para esse limite. Se você definir um cupom para durar indefinidamente quando um cliente o utilizar, mas o cupom tiver uma data de expiração, qualquer cliente ao qual esse cupom for concedido terá o desconto desse cupom indefinidamente. Novos clientes não poderão aplicar o cupom após a data de expiração. ## Códigos promocionais Os códigos promocionais são códigos visíveis ao cliente 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 durante o pagamento. Se você implementou o *portal do cliente* (The customer portal is a secure, Stripe-hosted page that lets your customers manage their subscriptions and billing details) e ativou os códigos promocionais, os clientes podem aplicar um desconto ao fazer upgrade ou downgrade de suas assinaturas existentes no portal. > 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. O portal do cliente exibe os códigos promocionais aplicados a uma assinatura. Se você não quiser permitir que os clientes apliquem o código promocional ou o compartilhem com outras pessoas, você deve [definir limites para o código promocional](https://docs.stripe.com/billing/subscriptions/coupons.md#promo-code-config) ou [aplicar um cupom](https://docs.stripe.com/billing/subscriptions/coupons.md#discount-subscriptions) diretamente. 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](https://docs.stripe.com/api/subscription_items/object.md) - [Objetos de item da fatura](https://docs.stripe.com/api/invoiceitems/object.md) - [Objetos Subscriptions](https://docs.stripe.com/api/subscriptions/object.md) ao fazer uma atualização - Fases futuras em [objetos Subscription Schedule](https://docs.stripe.com/api/subscription_schedules/object.md) ### Criar códigos promocionais #### Dashboard Você pode criar um código promocional no Dashboard ao [criar um cupom](https://docs.stripe.com/billing/subscriptions/coupons.md#create-a-coupon). O **Código** 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 com o mesmo **Código**, mas não pode reutilizar esse **Código** em uma promoção que qualquer cliente possa resgatar. - Se você criar um código promocional resgatável por qualquer cliente, não será possível criar outro código promocional ativo com o mesmo **código**. - Você pode criar um código promocional com um **Código**, [desativá-lo](https://docs.stripe.com/billing/subscriptions/coupons.md#deactivate) e em seguida, criar um novo código promocional com o mesmo **Código**. 1. No Dashboard, na página [Criar um cupom](https://dashboard.stripe.com/test/coupons/create), clique no botão **Usar códigos promocionais voltados para o cliente**. 2. Insira um código. Esse é o código que um cliente insere durante o pagamento para resgatar o desconto. Se você não definir um código, a Stripe gerará um para você. 3. Selecione os requisitos para o código promocional. Por exemplo, você pode restringir o cupom a ser válido apenas para o primeiro pedido. #### API 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](https://docs.stripe.com/api/promotion_codes.md), especifique um `Coupon` existente e eventuais restrições (por exemplo, ativado apenas para um ID de `Customer` específico). Você pode especificar a cadeia de código (por exemplo, `FALL25OFF`) no parâmetro `code`. Se você não fornecer uma cadeia de código, a Stripe gera uma aleatória. #### Accounts v2 ```curl curl https://api.stripe.com/v1/promotion_codes \ -u "<>:" \ -d "coupon={{COUPON_ID}}" \ -d code=ALICE20 \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/promotion_codes \ -u "<>:" \ -d "coupon={{COUPON_ID}}" \ -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 #### Dashboard Para limitar um código promocional a um cliente específico, conclua estas etapas: 1. Na página [Criar um cupom](https://dashboard.stripe.com/test/coupons/create), selecione **Limitar a um cliente específico**. 2. Selecione o cliente relevante. Se você não especificar um cliente, qualquer cliente poderá resgatar o código promocional. #### API Para limitar um código promocional a um cliente específico, especifique uma `customer_account` ou `customer` ao criar o código promocional. Se você não especificar um cliente, qualquer cliente poderá resgatar o código promocional. ### Limitar ao primeiro pedido A configuração limita o cupom a clientes que não possuam histórico prévio de transações na sua plataforma. Isso impede que clientes utilizem o cupom se: - Tiverem iniciado um PaymentIntent, mesmo que o pagamento não tenha sido concluído. - Tiverem participado de um período de teste, ainda que posteriormente cancelado. #### Dashboard Para restringir um código promocional a clientes de primeira compra, na página [Criar um cupom](https://dashboard.stripe.com/test/coupons/create), selecione **Válido apenas para primeiro pedido**. #### API Limite o código promocional a clientes de primeira compra definindo o parâmetro `first_time_transaction` do atributo `restrictions`. ### Definir um valor mínimo #### Dashboard Para definir um valor mínimo qualificado para um código promocional, na página [Criar um cupom](https://dashboard.stripe.com/test/coupons/create), selecione **Exigir valor mínimo de pedido** e insira o valor mínimo. 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 o cupom aceitar várias moedas, o valor mínimo pode ser diferente por moeda. #### API 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 #### Dashboard Para definir uma data de validade para um código promocional, na página [Criar um cupom](https://dashboard.stripe.com/test/coupons/create), selecione **Adicionar uma data de validade** e a data e hora em que o código promocional vence. Se o cupom correspondente já tiver uma data de validade definida, a data de validade do código promocional não pode ser posterior à do cupom. Por exemplo, você pode ter planos de oferecer um cupom por um ano, mas deseja que ele possa ser resgatado apenas por uma semana após o recebimento por parte do cliente. Para isso, defina a data de validade do cupom para daqui a um ano e a data de validade de cada código promocional para uma semana após a sua criação. #### API 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ê pode ter planos de oferecer um cupom por um ano, mas deseja que ele possa ser resgatado apenas por uma semana após o recebimento por parte do cliente. 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 #### Dashboard Para definir o número total de vezes que o código promocional pode ser resgatado pelos seus clientes, selecione **Limitar o número de vezes que este código pode ser resgatado** na página [Criar um cupom](https://dashboard.stripe.com/test/coupons/create) e digite o número. Veja [Limites de resgate](https://docs.stripe.com/billing/subscriptions/coupons.md#redemption-limits) para obter detalhes. Se o cupom correspondente já tiver um número máximo de vezes definido, os resgates máximos do código promocional não podem ser maiores do que os do cupom. #### API Limite o número total de vezes que um código promocional pode ser resgatado pelos seus clientes usando `max_redemptions`, que funciona de forma semelhante aos cupons. Se o cupom subjacente já tiver `max_redemptions` definido, o código promocional `max_redemptions` não poderá ser maior que o cupom. Veja [Limites de resgate](https://docs.stripe.com/billing/subscriptions/coupons.md#redemption-limits) para obter detalhes. ### Desativar códigos promocionais #### Dashboard Para desativar um código promocional, siga estas instruções: 1. No Dashboard, abra a página [Produtos](https://dashboard.stripe.com/test/products?active=true). 2. Clique em **Cupons**. 3. Clique no cupom cujo código promocional deseja desativar. 4. Na linha do código promocional relevante, clique no menu de navegação (⋯). 5. Clique em **Arquivar código promocional**. 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 limite máximo de resgate ou sua data de validade, ele se tornará permanentemente inativo. Esses códigos promocionais não podem ser reativados. #### API 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](https://docs.stripe.com/api.md#create_subscription) - Quando você [atualiza a assinatura existente de um cliente](https://docs.stripe.com/api.md#update_subscription) #### Dashboard 1. No Dashboard, acesse **Cobrança** > **Assinaturas**. 2. Clique na assinatura relevante. 3. Clique em **Ações** > **Atualizar assinatura** > **Adicionar cupom**. 4. Clique em um código promocional no menu suspenso e clique em **Enviar**. #### API 1. Recupere o `PromotionCode` correspondente [listando seus PromotionCodes](https://docs.stripe.com/api/promotion_codes/list.md) e fornecendo a string de código que seu cliente inseriu no parâmetro [code](https://docs.stripe.com/api/promotion_codes/list.md#list_promotion_code-code). 2. Para aplicar o código promocional, use o ID do código promocional na chamada da API a seguir: #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "discounts[0][promotion_code]={{PROMOTIONCODE_ID}}" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "discounts[0][promotion_code]={{PROMOTIONCODE_ID}}" ``` ### Adição de códigos promocionais ao Checkout Ative os códigos promocionais com a API definindo o parâmetro [allow_promotion_codes](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-allow_promotion_codes) nas Checkout Sessions. Quando `allow_promotion_codes` está ativado em uma Checkout Session, o Checkout inclui uma caixa para que seus clientes insiram e resgatem códigos promocionais. ![Campo de código promocional no Checkout](https://b.stripecdn.com/docs-statics-srv/assets/promo_code_checkout.c07ef6d4f0b1b3f9a8a7e4bbba83d56f.png) 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](https://docs.stripe.com/api/.md#discounts) resgatados à lista de cobranças de um cliente. Isso pode ser feito ao [criar uma assinatura](https://docs.stripe.com/api.md#create_subscription) ou [atualizando a assinatura existente de um cliente](https://docs.stripe.com/api.md#update_subscription). 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 *then* 5 USD de desconto - 5 USD de desconto *then* 20% de desconto #### Dashboard 1. No Dashboard, acesse **Cobrança** > **Assinaturas**. 2. Clique na assinatura relevante. 3. Clique em **Ações** > **Atualizar assinatura** > **Adicionar cupom**. 4. Clique em cupons nos menus suspensos e em **Enviar**. 5. Clique no produto relevante. 6. Clique em **Adicionar cupons**. 7. Clique em cupons nos menus suspensos e em **Enviar**. #### API #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_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" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -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 usar um cupom e um código promocional gerados a partir do mesmo cupom. - Não é possível usar um cupom e um desconto gerados 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á tiver definido mais de um desconto em uma assinatura com o novo parâmetro `discounts`, não poderá atualizar a assinatura com o parâmetro `coupon` ou `promotion_code` obsoleto. Da mesma forma, você não poderá atualizar as fases de um cronograma com o parâmetro `coupon` ou `promotion_code`l obsoleto se tiver definido mais de um desconto em uma fase anterior. A atualização de `discounts` não gera rateios nem fatura por si só. Os novos descontos serão aplicados na próxima vez que a assinatura gerar uma fatura. > Atualizar códigos promocionais, cupons ou descontos no nível da assinatura, por si só, não cria itens da fatura pro rata. Apenas alterações que afetam valores faturáveis para o ciclo de faturamento atual criam pro rata — por exemplo, alterar o `preço` ou a `quantidade` de um item da assinatura, adicionar ou remover itens da assinatura ou alterar âncoras do ciclo de cobrança. > > No entanto, quando você combina uma alteração de desconto com uma atualização que aciona pro rata (como alterar a quantidade de um item e modificar um desconto na mesma chamada da API), a Stripe calcula os valores de pro rata usando o estado atualizado de preços e descontos da assinatura. O débito ou crédito de pro rata reflete os descontos modificados. ## 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](https://docs.stripe.com/api.md#customer_object-balance) negativo ao cliente. - Adicione [itens de fatura](https://docs.stripe.com/billing/invoices/subscription.md#adding-draft-invoice-items) negativos. - Adicione um [segundo preço](https://docs.stripe.com/products-prices/manage-prices.md#create-price) 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ê. ## See also - [Alterar assinaturas](https://docs.stripe.com/billing/subscriptions/change.md) - [Pro rata](https://docs.stripe.com/billing/subscriptions/prorations.md) - [Trabalhar com faturas](https://docs.stripe.com/billing/invoices/subscription.md) - [API de cupons](https://docs.stripe.com/api.md#coupons) - [API de códigos promocionais](https://docs.stripe.com/api.md#promotion_codes)