Cobranças proporcionais

Gerencie cobranças proporcionais para assinaturas modificadas.

O aspecto mais complexo da alteração de assinaturas existentes são as cobranças proporcionais, em que o cliente paga uma porcentagem do custo da assinatura para refletir o uso parcial. Esta página explica como as cobranças proporcionais funcionam com assinaturas e como gerenciá-las para seus clientes.

Como funcionam as cobranças proporcionais

Por exemplo, atualizar ou voltar a uma versão anterior de uma assinatura pode resultar em cobranças pro rata. Se um cliente atualizar de um plano mensal de 10 USD para uma opção de 20 USD, serão cobrados valores pro rata pelo tempo gasto em cada opção. Se a alteração ocorrer na metade do período de cobrança, o cliente recebe uma cobrança adicional de 5 USD: -5 USD pelo tempo não utilizado no preço inicial, e 10 USD pelo tempo restante no novo preço.

A cobrança proporcional garante uma cobrança precisa dos valores, mas pode resultar em valores de pagamento diferentes dos esperados. Cobranças proporcionais negativas não são reembolsadas automaticamente nem são cobradas imediatamente, embora essas ações possam ser realizadas manualmente.

Você pode visualizar uma cobrança proporcional para ver o valor antes de aplicar as mudanças. Para saber mais sobre como funcionam as cobranças proporcionais de crédito, leia nosso guia.

Cobranças proporcionais e descontos

Todos os itens da fatura que são pro rata (prorations=true) são definidas comodiscountable=false. Os descontos aplicados a uma fatura contendo pro rata são aplicados apenas a itens da fatura e itens de linha da fatura que não são pro rata. Descontos aplicados anteriormente à assinatura e que afetem o valor pro rata são refletidos no valor pro rata do item da fatura.

Opções não pro rata mostram ajustes de desconto em discount_amounts.

O que desencadeia cobranças proporcionais

Por padrão, os seguintes cenários resultam em uma cobrança proporcional:

Alterar para outro preço com custo básico diferente
Alterar para outro preço com intervalo de cobrança diferente
Adicionar um período de avaliação a assinaturas ativas
Alterar a quantidade
Assinaturas licenciadas (por usuário) (porque são cobradas no início de cada período de cobrança)

Crie manualmente seus próprios rateios

Para calcular suas próprias cobranças proporcionais fora da Stripe e adicioná-las à assinatura, passe add_invoice_items com um unit_amount negativo (igual ao valor proporcional calculado) a estes endpoints:

Quando são aplicadas cobranças proporcionais

Cobranças proporcionais ocorrem apenas em cobranças antecipadas do ciclo de cobrança. Cobrança por uso não está sujeito a cobrança proporcional.

O valor proporcional é calculado assim que o API atualiza a assinatura. As datas de início e término do período de cobrança atual são usadas para calcular o custo da assinatura antes e depois da alteração.

Cobranças proporcionais e faturas não pagas

A Stripe calcula cobranças proporcionais com base no estado da assinatura no momento de uma atualização, presumindo que quaisquer faturas anteriores da assinatura serão pagas. Se um cliente alterar a assinatura e tiver uma fatura não paga do período atual, ele poderá receber um crédito pelo tempo não utilizado no plano de preço mais alto, mesmo que ainda não tenha pago pelo período.

Para evitar cobranças por períodos não pagos, você pode desativar as cobranças proporcionais quando a última fatura da assinatura estiver em aberto. Ao atualizar a assinatura, defina proration_behavior como none. Selecione uma das seguintes abordagens:

Para manter o ciclo de cobrança original: crie manualmente uma fatura avulsa para qualquer nova cobrança.
Para cobrar imediatamente pelo novo plano e redefinir o ciclo de faturamento: Defina billing_cycle_anchor como now. Para mais detalhes, consulte Redefinir o ciclo de cobrança para o horário atual.

Qualquer uma dessas abordagens pode levar a pagamentos em duplicidade caso o cliente acabe pagando a fatura antiga. Para evitar isso, anule a fatura não paga.

Impostos e cobranças proporcionais

Para saber como funcionam impostos com cobranças proporcionais, consulte Recolher impostos para pagamentos recorrentes.

Cobranças proporcionais de crédito

Os pro rata de crédito são emitidos quando os clientes fazem downgrade de suas assinaturas ou cancelam itens de assinatura antes do final do período de cobrança. A Stripe oferece duas abordagens para calcular os pro rata de crédito, dependendo se você definiu o modo_de_faturamento da sua assinatura como classic ou flexible.

Lógica de cálculo sem cobranças proporcionais

No cenário a seguir, você atualiza uma assinatura mensal de 10 USD para 20 USD com o proration_behavior definido como none por 10 dias. Não há débito anterior para basear a assinatura. Posteriormente, você faz o downgrade da assinatura para 10 USD por mês com o proration_behavior definido como always_invoice.

Para configurar este cenário, primeiro crie uma assinatura de 10 USD por mês em 1º de abril:

A resposta inclui a fatura criada para esta assinatura:

Create subscription response
{
  id: "sub_123",
  latest_invoice: {
    id: "in_123",
    total: 10_00,
    currency: "usd"
    }
}

Em seguida, em 11 de abril, você atualiza a assinatura para 20 USD por mês sem criar pro rata:

A fatura mais recente permanece inalterada porque proration_behavior é none:

Upgrade subscription response
{
  id: "sub_123",
  latest_invoice: {
    id: "in_123"
  }
}

Por fim, em 21 de abril, você faz downgrade da assinatura para 10 USD por mês e cria pro rata:

Clássico Flexível

A lógica de cálculo de rateio billing_mode=classic cria um pro rata de crédito com base no preço atual, mesmo que o cliente nunca tenha pago a taxa mensal de 20 USD. A fatura mais recente credita um terço do mês no valor de 20 USD (-), mesmo que o cliente nunca tenha pago o preço price_20_monthly. Ela também debita um terço do mês no valor de 10 USD (). A lógica de cálculo habilitada com billing_mode=flexible cria um pro rata de crédito com base no último preço cobrado pelo item de assinatura. Nesse caso, a fatura mais recente credita um terço do mês pelo preço mensal de 10 USD cobrado em 1º de abril (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 se cancelam, de modo que o total da fatura é 0 USD.

Clássico	Flexível
A lógica de cálculo de rateio `billing_mode=classic` cria um pro rata de crédito com base no preço atual, mesmo que o cliente nunca tenha pago a taxa mensal de 20 USD. A fatura mais recente credita um terço do mês no valor de 20 USD (-), mesmo que o cliente nunca tenha pago o preço `price_20_monthly`. Ela também debita um terço do mês no valor de 10 USD ().	A lógica de cálculo habilitada com `billing_mode=flexible` cria um pro rata de crédito com base no último preço cobrado pelo item de assinatura. Nesse caso, a fatura mais recente credita um terço do mês pelo preço mensal de 10 USD cobrado em 1º de abril (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 se cancelam, de modo que o total da fatura é 0 USD.
`# billing_mode = classic { id: "sub_123", latest_invoice: { id: "in_456", total: -3_34, currency: "usd" } }`	`# billing_mode = flexible { id: "sub_123", latest_invoice: { id: "in_456", total: 0, currency: "usd" } }`

# billing_mode = classic
  {
    id: "sub_123",
    latest_invoice: {
      id: "in_456",
      total: -3_34,
      currency: "usd"
    }
  }

# 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_off 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, você cria uma assinatura com vários itens e um cupom em 1º de fevereiro:

O que retorna esta resposta:

Create subscription with multiple items and a coupon response
{
  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 mensal 10 USD usando billing_mode=classic:

Para cancelar o mesmo item usando billing_mode=flexible:

Clássico	Flexível
O comportamento padrão distribui um cupom de 5 USD para cada item ( cada), cancelando o item mais barato (5 USD) e resultando em um reembolso de . A Stripe calcula o total com a fórmula `-0,5 x (preço de 10 USD - cupom de 5 USD) = -2,50 USD`.	O comportamento flexível reflete o desconto proporcional aplicado ao item cancelado, em vez de aplicar o valor total do desconto ao cálculo pro rata. A Stripe calcula o total usando a fórmula `-0,5 x (preço de US$ 10 - valor do desconto de US$ 1,66) = -4,17 USD`.
`# billing_mode = classic { "id": "sub_123", "latest_invoice": { "id": "in_456", "total": -250, "currency": "usd" } }`	`# billing_mode = flexible { "id": "sub_123", "latest_invoice": { "id": "in_789", "total": -417, "currency": "usd" } }`

Exibir uma cobrança proporcional

É possível criar uma prévia da fatura para visualizar alterações na assinatura. Esta chamada da API não modifica a assinatura. Em vez disso, ele retorna a fatura com base apenas nos parâmetros que você passar. Alterar price ou quantity resulta em cobrança proporcional. Este exemplo altera o price e define uma data para a cobrança proporcional.

Você pode expandir a resposta de exemplo abaixo para ver:

O crédito pelo tempo não utilizado no preço anterior nas linhas 36 a 38.
O custo pelo tempo gasto no novo preço nas linhas 107 a 109.
O novo subtotal e o total pela fatura nas linhas 276 a 279.

{
  "id": "upcoming_in_1OujwkClCIKljWvsq5v2ICAN",
  "account_country": "US",
  "account_name": "Test account",
  "amount_due": 3627,
  "amount_paid": 0,
  "amount_remaining": 3627,
  "application_fee_amount": null,
  "attempt_count": 0,
  "attempted": false,

Use essas informações para confirmar as alterações junto ao cliente antes de modificar a assinatura. Como a Stripe faz a cobrança proporcional para a segunda, os valores proporcionais podem mudar entre o momento em que são visualizados e o momento em que a atualização é feita. Para evitar isso, passe um subscription_proration_date para a fatura ao visualizar uma prévia da alteração. Quando você atualizar a assinatura, passe a mesma data usando o parâmetro proration_date em uma assinatura para que a cobrança proporcional seja calculada ao mesmo tempo.

Controlar o comportamento da cobrança proporcional

A cobrança proporcional é controlada pelo parâmetro proration_behavior, que tem três opções possíveis de parâmetros: create_prorations, always_invoice e none.

Comportamento padrão

O parâmetro padrão para proration_behavior é create_prorations, que cria itens de fatura proporcionais quando for aplicável. Esses itens de cobrança proporcional só são faturados imediatamente em determinadas condições.

Criar cobranças proporcionais imediatas

Para cobrar imediatamente um cliente por uma alteração em uma assinatura no mesmo ciclo de cobrança, defina proration_behavior como always_invoice quando modificar a assinatura. A cobrança proporcional é calculada e uma fatura é gerada imediatamente.

Desativar cobranças proporcionais

Para desativar as cobranças proporcionais por solicitação, defina o parâmetro proration_behavior como none. Nenhum parâmetro desativa todas as cobranças proporcionais futuras de uma assinatura. Para desativar as cobranças proporcionais indefinidamente, defina proration_behavior como none para cada solicitação que gerar cobranças proporcionais:

Quando as cobranças proporcionais são desativadas, os clientes são cobrados no valor total no novo preço quando a próxima fatura é gerada.