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 os rateios

Por exemplo, atualizar ou voltar a uma versão anterior de uma assinatura pode resultar em cobranças proporcionais. Se um cliente atualizar de um plano mensal de 10 USD para uma opção de 20 USD, serão cobrados valores proporcionais pelo tempo gasto em cada opção. Se a alteração ocorrer na metade do período de faturamento, 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 a cobrança precisa, mas pode resultar em valores de pagamento diferentes dos esperados. Cobranças proporcionais negativas não são reembolsadas automaticamente, e cobranças proporcionais positivas não 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.

Cobranças proporcionais e descontos

Qualquer ajuste de descontos é refletido no valor do item na fatura de cobrança proporcional. Descontos adicionais em nível de item da fatura ou em nível de item de linha da fatura não se aplicam às cobranças proporcionais porque eles têm discountable=false.

Esse comportamento é diferente de cobranças não proporcionais, que mostram ajustes de desconto em discount_amounts.

O que aciona 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 faturamento 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 faturamento)

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 unit_amount negativos (igual ao valor proporcional calculado) a estes endpoints:

• CriarAssinatura
• AtualizarAssinatura
• CriarCronogramaAssinatura
• AtualizarCronogramaAssinatura

Quando são aplicadas cobranças proporcionais

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

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

Impostos e cobranças proporcionais

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

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 junto ao cliente antes de modificar a assinatura. Como a Stripe faz as cobranças proporcionais por segundo, 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.

# 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 sob certas condições.

Criar cobranças proporcionais imediatas

Para cobrar imediatamente um cliente por uma alteração em uma assinatura no mesmo ciclo de faturamento, defina proration_behavior como always_invoice quando você 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:

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.