Ativar comportamento flexível para assinaturas
Use o modo de cobrança para controlar como as cobranças proporcionais e as faturas de assinaturas são calculadas e orquestradas.
Atualmente, a Stripe calcula os valores da cobrança proporcional de crédito de acordo com o valor do preço atual, imposto, quantidade e últimos descontos usados do item de assinatura.
Você pode configurar billing_ para ativar outra lógica de cobrança proporcional que calcula cobranças proporcionais de crédito com base no valor original debitado anteriormente de um cliente.
Visualização pública
Para ativar a nova lógica de cálculo de cobrança proporcional configurandobilling_, você deve atualizar sua versão da API para 2025-04-30. ou posterior.
O comportamento atual pode causar cobranças proporcionais inesperadas quando as alíquotas de impostos de um cliente mudam, você desabilita as cobranças proporcionais de débito ou usa valores complexos nos cupons. A lógica aprimorada de cobrança proporcional calcula as cobranças proporcionais de crédito com base apenas no valor original debitado anteriormente de um cliente. Quando um cliente faz uma alteração na assinatura que resulta em um crédito, a Stripe calcula a cobrança proporcional usando o valor cobrado anteriormente. Esse cálculo ocorre independentemente de alterações posteriores feitas à assinatura. A Stripe recomenda usar billing_ se as limitações da prévia pública não se aplicarem a você.
Limitações da prévia pública Prévia pública
Durante a prévia pública, billing_ não é compatível com todas as funcionalidades do Stripe Billing.
Quando você configura billing_:
- Cobrança por uso não é aceita.
- Cálculo de imposto automático não é aceito.
- Avaliações não são aceitas.
- Endpoints de cotações não são aceitos.
- Não é possível criar assinaturas retroativas.
- Não é possível suspender a cobrança de pagamentos em assinaturas.
Se você usar esses recursos com billing_, eles retornarão um código de erro 400.
Configurar o modo de cobrança Prévia pública
Você pode configurar billing_ em assinaturas específicas e ter várias assinaturas com configurações de billing_mode diferentes. Não é possível alterar o billing_ de flexible para classic. Isso garante lógica e comportamento consistentes durante todo o ciclo de vida de cada assinatura. Você pode migrar assinaturas existentes de billing_ para billing_.
Quando você configura billing_, ele também atualiza o subscription.trial_start para refletir a data de início da avaliação mais recente.
Migrar assinaturas para o modo de cobrança flexível Public preview
Você pode migrar assinaturas existentes de billing_ para billing_ usando o endpoint de migração de assinatura. A migração para o modo de cobrança flexible é um processo unidirecional. Após migrar uma assinatura para o modo flexible, não é possível revertê-la para o modo classic. Isso garante uma lógica consistente de cobrança proporcional durante todo o ciclo de vida da assinatura.
Quando você migra uma assinatura, o carimbo de data e hora billing_ é atualizado para refletir quando o billing_ é alterado.
Mudanças no modo de cobrança flexível
Definir billing_ em uma assinatura altera o comportamento dos objetos Subscription ao longo do ciclo de vida e em resposta a upgrades, downgrades e cancelamentos.
Lógica de cálculo sem cobranças proporcionais
No seguinte cenário, você atualiza uma 10 USD assinatura mensal para 20 USD com o proration_ definido como none por 10 dias. Não há débito anterior para baseá-lo. Posteriormente, você faz o downgrade da assinatura para 10 USD por mês com proration_ definido como always_.
Para configurar esse cenário, primeiro você cria uma assinatura de 10 USD/mês em 2025-04-01:
A resposta inclui a fatura criada para esta assinatura:
{ id: "sub_123", latest_invoice: { id: "in_123", total: 10_00, currency: "usd" } }
Em 2025-04-11, você atualiza a assinatura para 20 USD/mês sem criar cobranças proporcionais:
A fatura mais recente permanece inalterada porque proration_ é none:
{ id: "sub_123", latest_invoice: { id: "in_123" } }
Finalmente, em 2025-04-21, você faz um downgrade da assinatura para 10 USD/mês e cria cobranças proporcionais:
A lógica padrão de cálculo proporcional cria uma cobrança proporcional de crédito com base no preço atual, mesmo que o cliente nunca tenha pago a taxa de 20 USD/mês. A última fatura credita um terço do mês por 20 USD (-6.67 USD), mesmo que o cliente nunca tenha pago pelo preço price_. Além disso, debita um terço do mês no valor de 10 USD (3.33 USD).
A lógica de cálculo habilitada com billing_ cria uma cobrança proporcional de crédito com base no último preço faturado para o item de assinatura. Nesse caso, a última fatura credita um terço de um mês pelo preço de 10 USD/mês cobrado em 2025-04-01 (3.33 USD) e debita um terço do mês pelo preço de 10 USD (3.33 USD). O crédito e o débito são cancelados, então o total da fatura é 0 USD.
# Default behavior # billing_mode = classic { id: "sub_123", latest_invoice: { id: "in_456", total: -3_34, currency: "usd" } }
# New behavior # billing_mode=flexible { id: "sub_123", latest_invoice: { id: "in_456", total: 0, currency: "usd" } }
Lógica de cálculo para cupons aplicados a vários itens de assinatura
A Stripe pondera o cupom amount_ no rateio de crédito para evitar cobranças em excesso.
No seguinte cenário, um cupom de 5 USD é alocado de forma desigual a uma assinatura mensal de 25 USD para um item de 10 USD e um item de 20 USD.
Para configurar esse cenário, crie uma assinatura com vários itens e um cupom em 2025-02-01:
O que retorna esta resposta:
{ id: "sub_123", latest_invoice: { id: "in_123", total: 25_00, currency: "usd", lines: { data: [ { id: "ili_1", amount: 10_00, price: "price_10_monthly", discount_amounts: [{ discount: "di_a", amount: 1_66 }] }, { id: "ili_2", amount: 20_00, price: "price_20_monthly", discount_amounts: [{ discount: "di_a", amount: 3_34 }] }, ] } } }
Para cancelar o item de assinatura de 10 USD/mês usando billing_:
Para cancelar o mesmo item usando billing_:
O comportamento padrão distribui um cupom de 5 USD para cada item (2.5 USD cada), cancelando o item mais barato (5 USD) e resultando em um reembolso de 2.5 USD. A Stripe calcula o total com a fórmula -0.
O novo comportamento reflete o desconto proporcional aplicado ao item cancelado, em vez de aplicar o valor do desconto total ao cálculo proporcional. A Stripe calcula o total usando a fórmula -0..
# Default behavior # billing_mode = classic { "id": "sub_123", "latest_invoice": { "id": "in_456", "total": -250, "currency": "usd" } }
# New behavior # billing_mode = flexible { "id": "sub_123", "latest_invoice": { "id": "in_789", "total": -417, "currency": "usd" } }
Redefinições de âncora de ciclo de cobrança
Quando você altera uma assinatura, o billing_cycle_anchor não é redefinido implicitamente. Por exemplo, mudar uma assinatura para um preço diferente com um intervalo recorrente diferente ou mudar o cancel_at para uma data anterior à próxima vez que os ciclos de assinatura não redefinem o billing_.
Datas de início e término da avaliação
O subscription. usa a data de início da avaliação mais recente para assinaturas com avaliações subsequentes.