Cobranças proporcionais

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:

O que não aciona rateios

Muitas atualizações de assinatura não afetam o faturamento ou geram rateios. Faça essas atualizações a qualquer momento sem criar itens de fatura pro rata:

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:

• CreateSubscription
• UpdateSubscription
• CriarCronogramaAssinatura
• AtualizarCronogramaAssinatura

Quando são aplicadas cobranças proporcionais

Os pro ratas aplicam-se apenas a cobranças realizadas antes do período de cobrança. A cobrança por uso não está sujeita a pro rata.

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 os pro ratas com base no status da assinatura no momento da atualização, presumindo que todas as faturas anteriores da assinatura serão eventualmente pagas. Se um cliente alterar sua assinatura enquanto tiver uma fatura não paga referente ao período atual, ele poderá receber um crédito pelo tempo não utilizado no plano de maior valor, mesmo que ainda não tenha pago por esse tempo.

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:

1. Para manter o período de cobrança original: crie uma fatura única manualmente para novas cobranças.
2. Para cobrar imediatamente pelo novo plano e redefinir o período de cobrança: Defina billing_cycle_anchor como now. Para obter mais detalhes, consulte Redefinir o período de cobrança como a hora 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:

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][price]"=price_10_monthly

A resposta inclui a fatura criada para esta assinatura:

{
  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:

curl https://api.stripe.com/v1/subscriptions/sub_123 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][id]"=sub_item_1 \
  -d "items[0][price]"=price_20_monthly \
  -d proration_behavior=none

A fatura mais recente permanece inalterada porque proration_behavior é none:

{
  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:

curl https://api.stripe.com/v1/subscriptions/sub_123 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][id]"=sub_item_1 \
  -d "items[0][price]"=price_10_monthly \
  -d proration_behavior=always_invoice

# 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:

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][price]"=price_20_monthly \
  -d "discounts[0][coupon]"=five_dollars_off

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 mensal de 10 USD:

curl https://api.stripe.com/v1/subscription_items/si_10_monthly \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d proration_behavior=create_prorations

Quando um item de assinatura é excluído, o billing_mode associado a essa assinatura afeta o modo como o rateio é calculado da seguinte forma:

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

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

# Set proration date to this moment:
proration_date = Time.now.to_i

subscription = Stripe::Subscription.retrieve('sub_49ty4767H20z6a')

# See what the next invoice would look like with a price switch
# and proration set:
items = [{
  id: subscription.items.data[0].id,
  price: 'price_CBb6IXqvTLXp3f', # Switch to new price
}]

invoice = Stripe::Invoice.create_preview({
  customer: 'cus_4fdAW5ftNQow1a',
  subscription: 'sub_49ty4767H20z6a',
  subscription_details: {
    items: items,
    proration_date: proration_date,
  }
})

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 com o cliente antes de modificar a assinatura. Como o Stripe é rateado ao segundo, os valores rateados podem mudar entre o momento da visualização e o momento da atualização. Para evitar isso, passe o valor subscription_details.proration_date ao criar uma prévia. Ao atualizar a assinatura, passe a mesma data usando o parâmetro proration_date em uma assinatura para que o rateio seja calculado ao mesmo tempo.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

subscription = Stripe::Subscription.update(
  'sub_49ty4767H20z6a',
  {
    items: [
      {
        id: subscription.items.data[0].id,
        price: 'price_CBb6IXqvTLXp3f',
      },
    ],
    proration_date: proration_date,
  }
)

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 um cliente imediatamente por uma alteração em uma assinatura no mesmo período de cobrança, defina proration_behavior como always_invoice ao modificar a assinatura. Isso calcula o pro rata e gera uma fatura 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:

curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "items[0][id]"="si_1AkFf6LlRB0eXbMtRFjYiJ0J" \
  -d "items[0][price]"="price_CBb6IXqvTLXp3f" \
  -d "proration_behavior"="none"

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.