Definir a data do ciclo de cobrança de assinaturas

O ciclo de faturamento de uma assinatura depende de dois fatores:

• O intervalo recorrente do preço ou preços, como mensal, anual, semanal e assim por diante.
• A âncora do ciclo de faturamento é o ponto de referência que alinha datas futuras do ciclo de faturamento. Ela define o dia da semana para intervalos de week, o dia do mês para intervalos de month e year, e o mês do ano para intervalos de year. O valor padrão é a data de criação da assinatura ou a data final da avaliação (se você estiver usando um período de avaliação). Você também pode definir explicitamente esse valor no momento da criação da assinatura.

Veja a seguir exemplos de assinaturas mensais com diferentes ciclos de faturamento:

• Uma assinatura mensal com uma data âncora do ciclo de faturamento de 2 de setembro sempre é faturada no segundo dia do mês.
• Uma assinatura mensal com uma data âncora de ciclo de faturamento de 31 de janeiro fatura o último dia do mês mais próximo da data âncora, ou seja, 28 de fevereiro (ou 29 de fevereiro em um ano bissexto), depois 31 de março, 30 de abril e assim por diante.
• Uma assinatura semanal com uma data âncora do ciclo de faturamento de sexta-feira, 3 de junho fatura todas as sextas-feiras a partir de então.

Os períodos de faturamento completos começam na primeira data da fatura completa, que normalmente é a data da âncora do ciclo de faturamento e sempre está alinhada por intervalos.

Especificar a âncora do ciclo de faturamento para novas assinaturas

Existem duas formas de definir a âncora do ciclo de faturamento em novas assinaturas:

• Use billing_cycle_anchor_config para calcular o carimbo de data e hora para você (somente assinaturas mensais ou anuais).
• Use billing_cycle_anchor para aceitar diretamente o carimbo de data e hora.

Se estiver criando uma assinatura mensal ou anual, recomendamos usar o parâmetro billing_cycle_anchor_config, pois ele considera automaticamente os meses curtos e anos bissextos. Se estiver criando uma assinatura diária ou semanal, ou se preferir definir a data do ciclo da sua assinatura usando um carimbo de data e hora, use o parâmetro billing_cycle_anchor diretamente.

Usar billing_cycle_anchor_config

Para criar uma integração com assinaturas mensais ou anuais, use billing_cycle_anchor_config em criar assinatura para especificar o dia do mês no qual a âncora será feita.

Defina day_of_month como 31 para criar uma assinatura mensal com ciclo no final do mês, mesmo em meses com menos de 31 dias. Se um mês tiver menos de 31 dias, a assinatura reinicia o ciclo no último dia desse mês.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "items[0][price]"=
{{PRICE_ID}} \
  -d "billing_cycle_anchor_config[day_of_month]"=31

Você também pode especificar month para controlar o mês do ano para a âncora em assinaturas de vários meses ou anuais.

Para definir suas assinaturas anuais no dia 1º de julho, crie uma assinatura anual com um month de 7 e day_of_month de 1.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "items[0][price]"=
{{PRICE_ID}} \
  -d "billing_cycle_anchor_config[month]"=7 \
  -d "billing_cycle_anchor_config[day_of_month]"=1

Você pode especificar o mês, o dia, a hora, o minuto e o segundo exatos para a âncora do ciclo de cobrança usando billing_cycle_anchor_config. Se você não especificar a hora, o minuto e o segundo, o padrão será os valores do horário de criação da assinatura.

A âncora do ciclo de cobrança usa UTC (Horário Universal Coordenado). Por exemplo, se você criar uma assinatura usando billing_cycle_anchor_config às 5 PM EST sem especificar a hora, a hora será registrada no sistema como 10 PM UTC.

billing_cycle_anchor_config não aceita ancoragem em uma data de início retroativa.

Por exemplo, se você tiver uma assinatura mensal existente com um carimbo de data e hora billing_cycle_anchor que contém o dia do mês, a hora, o minuto e o segundo de 15, 12, 30 e 0, poderá alinhar uma nova assinatura mensal a ele. Para fazer isso, defina day_of_month, hour, minute e second para corresponder aos mesmos valores, respectivamente.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "items[0][price]"=
{{PRICE_ID}} \
  -d "billing_cycle_anchor_config[day_of_month]"=15 \
  -d "billing_cycle_anchor_config[hour]"=12 \
  -d "billing_cycle_anchor_config[minute]"=30 \
  -d "billing_cycle_anchor_config[second]"=0

Se você usar billing_cycle_anchor_config, poderá resultar em um billing_cycle_anchor com mais de um período de faturamento no futuro. No entanto, a data da primeira fatura completa sempre ocorre em um período de faturamento desde a criação da assinatura ou do término de uma avaliação gratuita.

Por exemplo, suponhamos que você cria uma assinatura de intervalo de dois meses em fevereiro e a realiza no final de cada mês, definindo day_of_month como 31. O próximo mês, que tem 31 dias em intervalos de dois meses a partir de fevereiro, é agosto. Isso resulta em uma âncora de ciclo de faturamento em 31 de agosto. No entanto, a primeira data de fatura completa dessa assinatura ainda ocorre em fevereiro. Há um período inicial proporcional da criação da assinatura até 28 de fevereiro (ou 29 durante um ano bissexto), seguido por um período de faturamento completo de dois meses.

Usar billing_cycle_anchor

Você pode criar uma assinatura com uma âncora de ciclo de faturamento explícita usando a API Subscriptions ou o Checkout.

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

Alterar o ciclo de faturamento em assinaturas pré-existentes

Use a API Subscriptions ou o Dashboard para alterar a data de faturamento de uma assinatura existente usando uma das seguintes opções:

• Redefina a âncora do ciclo de faturamento para a hora atual.
• Adicione uma avaliação gratuita para definir automaticamente a data âncora para o final da avaliação. As avaliações normalmente começam quando você cria uma assinatura, mas também é possível aplicá-las a assinaturas existentes, permitindo creditar o cliente pelos dias restantes no ciclo anterior que ele já pagou.

A data do ciclo de cobrança muda nesses cenários. No entanto, se você criar ou atualizar uma assinatura com billing_mode[type]=flexible, a âncora do ciclo de cobrança permanecerá inalterada. Saiba mais sobre como configurar o modo de cobrança flexível e suas limitações.

• Se todos os preços tiverem valor zero, a adição de um ou mais preços pagos redefinirá imediatamente o período de cobrança. Consulte o guia de alteração de preços de assinatura para obter mais informações.
• O billing_cycle_anchor é redefinido para a data do cancel_at ao criar uma assinatura com cancel_at definido para uma data anterior aos próximos ciclos de assinatura ou ao modificar uma data existente de cancel_at em uma assinatura com um billing_cycle_anchor no futuro da nova data cancel_at.
• O billing_cycle_anchor é redefinido para o horário atual quando muda para um preço com recurring.interval diferente.

Redefinir o ciclo de faturamento para o tempo atual

Para redefinir a âncora do ciclo de cobrança, faça uma solicitação de atualização com billing_cycle_anchor definido como now. Isso define a âncora do ciclo de cobrança para o momento da solicitação de atualização. Quando você redefine a âncora do ciclo de cobrança, a Stripe envia imediatamente uma fatura. Ativar cobrança proporcional para creditar o cliente para qualquer dia já pago no período anterior. Desativar a cobrança proporcional pode resultar em cobranças excessivas ao cliente.

curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d billing_cycle_anchor=now \
  -d proration_behavior=create_prorations

Adicionar uma avaliação para alterar o ciclo de faturamento

Adicionar um período de avaliação não proporcional a uma assinatura existente permite configurar o ciclo de faturamento para qualquer data.

Normalmente, se estiver usando o período de avaliação para alterar o ciclo de faturamento sem emitir uma fatura proporcional, você desativa a cobrança proporcional porque a duração do período de avaliação considera a parte já paga do ciclo de faturamento anterior.

Por exemplo, se um cliente tiver uma assinatura ativa definida para faturar em 23 de julho e você introduzir um período de avaliação até 1º de agosto:

• O cliente recebe uma fatura de US$ 0 em 15 de julho.
• O cliente não é cobrado em 23 de julho.
• O cliente é cobrado em 1º de agosto, depois em 1º de setembro e assim por diante.
• O cliente já pagou até 23 de julho no ciclo anterior, então esse período “gratuito” não é realmente gratuito.
• O período entre 23 e 31 de julho não é cobrado.
• O novo ciclo faturado em 1º de agosto é um ciclo completo à taxa normal.

curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d trial_end=1611008505 \
  -d proration_behavior=none

Cobrança por uso

Com a cobrança por uso, o preço pago pelo cliente varia em função do consumo durante o ciclo de cobrança. Quando a alteração do ciclo de cobrança antecipa o término de um intervalo de assinatura, você cobra do cliente o uso acumulado durante o ciclo de cobrança reduzido.

Limites

Além do ciclo regular, é possível configurar assinaturas para cobrar sempre que o valor devido atingir um limite.

Se você tiver uma assinatura configurada para faturar dessa forma, será possível configurá-la para redefinir o ciclo da assinatura quando ele atingir o limite.