Definir assinaturas retroativamente

Você pode atribuir uma data passada a uma assinatura para faturar os clientes por períodos já decorridos. Isso é usado muitas vezes ao migrar para a Stripe ou para fins de manutenção de registros. O campo backdate_start_date especifica a data de início retroativa da assinatura. Você também tem a opção de faturar os clientes por esse tempo decorrido e definir a próxima data de cobrança.

Considerações sobre o modo de cobrança

A partir da versão da API 2025-04-30, o comportamento da data retroativa depende do billing_mode da sua assinatura:

Atribuir datas passadas e cobrar usuários

Às vezes, os usuários podem ter acesso ao seu serviço antes de você criar uma assinatura para eles, e você deseja cobrar esse acesso.

Uma fatura é criada com cobranças para o período entre as datas passada e atual.

Se uma assinatura tiver billing_mode=classic, a Stripe cria um valor proporcional único para o período retroativo com base em um intervalo imaginado a partir da data de início retroativa. Por exemplo, se você tiver um ciclo de cobrança mensal iniciando no primeiro dia do mês e definir backdate_start_date para 15 de fevereiro (em um ano bissexto), a Stripe calcula o valor proporcional com base em um mês imaginado de 15 de fevereiro a 15 de março. Como fevereiro tem 28 dias, o valor proporcional para os 14 dias a partir de 15 de fevereiro a 1º de março é exatamente a metade do valor de uma cobrança mensal normal.

Da mesma forma, se você definir backdate_start_date como 15 de janeiro, a Stripe baseia o cálculo proporcional em um mês imaginado de 15 de janeiro a 15 de fevereiro. Esse mês imaginado tem 31 dias, por isso, o valor proporcional para os 17 dias de 15 de janeiro a 1º de fevereiro é 17 dividido por 31 (aproximadamente 0,548) de uma cobrança mensal normal.

Você também pode visualizar o cálculo considerando a data inicial retroativa como a data inicial original. O início do primeiro período de cobrança completo passa a ser a data inicial atualizada.

Se uma assinatura tiver billing_mode=flexible, a Stripe gera itens de linha separados para cada ciclo de cobrança natural ocorrido durante o período retroativo. Isso significa que cada ciclo é tratado como se a Stripe tivesse faturado normalmente durante esse período.

Atribuir datas passadas sem cobrar usuários

Você também pode atribuir uma data passada a uma assinatura sem cobrar o cliente pelo período passado, o que pode ser usado em uma migração para a Stripe. Para fazer isso, passe proration_behavior: 'none' quando criar a assinatura. Isso define o start_date com o mesmo valor que backdate_start_date, mas não cobra o cliente pelo período passado.

Atribuir datas passadas e definir a âncora do ciclo de faturamento

Você pode combinar backdate_start_date e billing_cycle_anchor para atribuir uma data passada a uma assinatura e definir a âncora do ciclo de faturamento como uma data futura. Um item proporcional é criado na próxima fatura para o período entre a data de início passada e a âncora do ciclo de faturamento. Você pode usar isso durante migrações para a Stripe em que é preciso preservar a próxima data de faturamento das assinaturas enquanto cobra os clientes pelo período transcorrido.

Por exemplo, vamos supor que hoje seja 15 de outubro e você esteja migrando para a Stripe. Há uma assinatura que começou em 1º de setembro, e a próxima data de faturamento é 1º de novembro. Para migrar essa assinatura, crie outra assinatura e defina backdate_start_date como 1º de setembro e billing_cycle_anchor como 1º de novembro.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d backdate_start_date=1575176400 \
  -d billing_cycle_anchor=1572580800 \
  -d "items[0][price]"=
{{PRICE_ID}}

Uma fatura será emitida imediatamente com o valor proporcional para o período entre 1º de setembro e 1º de novembro. Além disso, a start_date da assinatura será definida como 1º de setembro. A Stripe emite a próxima fatura em 1º de novembro.

Atribuir uma data retroativa a uma atualização

Para definir a data efetiva de cobranças proporcionais ao atualizar uma assinatura, use o parâmetro proration_date. Passe um carimbo de data e hora Unix inteiro que ocorre dentro do período atual dos itens da assinatura. Se a assinatura utilizar uma programação de assinatura, verifique se o carimbo de data e hora é anterior à data de início da próxima fase do cronograma.

Você pode definir a proration_date anterior ao período atual somente durante o primeiro período de uma assinatura retroativa. Nessa situação, a proration_date deve ser no ou após a subscription[start_date] (a data de início retroativa). Nos demais casos, a proration_date não pode ser anterior ao current_period_start.