Cronogramas de assinatura

Saiba mais sobre os cronogramas de assinatura e como usá-los.

Use assinaturas programadas para automatizar alterações nas assinaturas ao longo do tempo. Você pode criar assinaturas diretamente de uma programação ou adicionar uma programação a uma assinatura existente. Use o atributo phases para definir as alterações que deseja fazer na assinatura. Depois de concluir todas as suas fases, uma programação é finalizada de acordo com seu end_behavior.

Estas são algumas alterações que você pode programar:

Iniciar uma assinatura em uma data futura
Atribuir uma data passada a uma assinatura
Fazer upgrade e downgrade de uma assinatura

As programações de assinatura estão disponíveis no Dashboard do Stripe Billing e na API. Este é um vídeo rápido sobre como funcionam os cronogramas de assinatura no Dashboard:

Cronogramas de assinatura no Dashboard

O restante deste documento explica as assinaturas programadas com mais detalhes. Para ver uma lista de exemplos, consulte a página de casos de uso.

Fases

Quando criar uma programação de assinatura, use o atributo phases para definir quando as alterações ocorrem e quais propriedades da assinatura devem ser alteradas. Por exemplo, você pode oferecer um cupom de 50% de desconto nos primeiros três meses da assinatura. Nesse cenário, você cria uma assinatura programadas em que a primeira fase dura três meses e contém o cupom de 50% de desconto. Na segunda fase, o cupom é removido e a assinatura volta ao custo normal. As fases devem ser sequenciais, ou seja, apenas uma fase pode estar ativa em um determinado momento. Você pode ter até 10 fases.

Defina a duração de uma fase

O intervalo de um preço determina a frequência de cobrança da assinatura. Por exemplo, um intervalo mensal é cobrado a cada mês. O atributo iterations é usado para especificar o número de iterações da fase. Multiplique esse valor pelo intervalo para determinar a duração da fase. Quando uma assinatura programada usa um preço com intervalo mensal e você define iterations=2, a fase dura dois meses.

O end_date de uma fase tem de ser o start_date da próxima fase. Use iterations para definir automaticamente o start_date e o end_date corretos. Você pode definir esses valores manualmente, mas a Stripe recomenda usar iterations. A definição manual de datas iniciais e finais é propensa a erros e só deve ser usada em casos de uso avançados.

Transição para a próxima fase

As transições de fase ocorrem automaticamente depois que a end_date de uma fase é alcançado. Quando uma fase começa, a Stripe atualiza a assinatura com base nos atributos da próxima fase. Você também pode ativar cobranças proporcionais para creditar ao usuário itens ou tempo do plano não utilizados.

Comportamento da cobrança proporcional

Há duas configurações diferentes de comportamento de cobrança proporcional que controlam como a Stripe gerencia os ajustes de cobrança durante alterações no cronograma de assinaturas:

Agendar comportamento de cobrança proporcional de atualização: O parâmetro proration_behavior de nível superior controla como gerenciar cobranças proporcionais durante a atualização de um cronograma de assinatura de uma maneira que afeta a configuração de cobrança da fase atual (como alterar preços ou quantidades).
Comportamento de cobrança proporcional de transição de fase: Cada fase tem seu próprio atributo proration_behavior que controla como a Stripe lida com cobranças proporcionais durante a transição para essa fase.

Agendar comportamento de cobrança proporcional de atualização

Quando você atualiza um cronograma de assinatura e altera a configuração de cobrança da current_phase, pode controlar como as cobranças proporcionais são tratadas usando o parâmetro de nível superior proration_behavior.

Esse parâmetro funciona de forma similar ao da API Update a subscription e aceita os seguintes valores:

(padrão) create_prorations: gere ajustes de cobrança proporcional para alterações na cobrança.
none: nenhuma cobrança proporcional é criada para a atualização.
always_invoice: gere cobranças proporcionais e finalize imediatamente uma fatura.

Alterações em campos que não são de cobrança (como metadados) não gerarão cobranças proporcionais, independentemente dessa configuração.

Comportamento da cobrança proporcional de transição de fase

Cada fase pode definir seu próprio proration_behavior para controlar o que acontece quando a assinatura entra nessa fase. Essa configuração se aplica especificamente a cobranças proporcionais geradas durante transições de fase e é salva como um campo na fase.

Por exemplo, se phases[1] aumenta a quantidade de 1 para 3 quando é iniciado, o proration_behavior em phases[1] determina como essas cobranças proporcionais são tratadas durante a transição de phases[0] para phases[1]:

(padrão) create_prorations: gere itens de fatura pendentes para alterações na cobrança.
none: nenhuma cobrança proporcional é criada ao entrar nesta fase.
always_invoice: gere cobranças proporcionais e crie imediatamente uma fatura ao entrar nessa fase.

Se você precisar alterar o modo como uma transição de fase futura lida com cobranças proporcionais, atualize a configuração proration_behavior na fase futura antes que ela se torne ativa.

Usar avaliações

Você pode adicionar períodos de avaliação definindo o final da avaliação em uma fase. Se quiser que a fase inteira seja uma avaliação, defina o valor de trial_end como o end_date da fase. Também é possível definir trial_end antes de end_date para avaliações que são apenas uma parte da fase. Na programação de atualizações, é preciso especificar o novo trial_end em cada fase.

Concluir um cronograma

Os cronogramas de assinatura terminam após a conclusão da última fase. Nesse momento, a assinatura fica como está e deixa de estar associada ao cronograma. Se você quiser cancelar uma assinatura após a conclusão da última fase de um cronograma, defina end_behavior como cancel. A cancel_on_date da assinatura não é definida até que a assinatura passe para a fase final.

Herança de atributos de fase

Quando uma fase é ativada, todos os atributos definidos na fase são definidos também na assinatura. Após o término da fase, os atributos permanecem os mesmos, exceto se modificados pela próxima fase ou se a programação não tiver nenhuma configuração padrão. Você pode definir alguns atributos em programações e fases, incluindo:

Atributo de programação	Atributo de fase
default_settings.billing_thresholds	phases.billing_thresholds
default_settings.collection_method	phases.collection_method
default_settings.default_payment_method	phases.default_payment_method
default_settings.invoice_settings	phases.invoice_settings

Se um desses atributos for definido na programação, será o padrão para todas as fases. Quando a mesma propriedade é definida na programação e na fase, o atributo da fase sobrepõe o atributo da programação. Esse comportamento é explicado a seguir:

Atributo da programação presente	Atributo da fase presente	Resultado
Não	Não	Assume o valor padrão das configurações do cliente ou da conta
Sim	Não	Atributo da programação definido
Sim	Sim	Atributo da fase definido
Não	Sim	Atributo da fase definido

Usar metadados de fase

Você pode usar fases do cronograma de assinaturas para definir metadados na assinatura associada. Isso permite que você controle os metadados em uma assinatura com atualizações agendadas.

Para usar metadados de fase com a API, defina metadados (メタデータ) nas fases do cronograma de uma assinatura. Quando a assinatura associada entrar em uma fase:

Quando as chaves dos metadados da fase com valores não vazios ainda não existem nos metadados da assinatura, os metadados da fase são adicionados aos metadados da assinatura.
Quando as chaves dos metadados da fase com valores não vazios já existem nos metadados da assinatura, os metadados da fase são usados para atualizar os metadados da assinatura.
Os metadados da fase com valores vazios são usados para cancelar a definição das chaves correspondentes nos metadados da assinatura.

Para cancelar a definição de todas as chaves nos metadados da assinatura, atualize diretamente a assinatura ou cancele a definição de cada chave individual nos metadados da assinatura. A atualização direta dos metadados da assinatura associada não afeta os metadados da fase atual.

O exemplo a seguir mostra uma programação de assinatura com duas fases, cada uma delas com seus próprios metadados:

{
  ...
  "object": "subscription_schedule",
  "phases": [
    { // Phase 1
      ...
      "metadata": {
        "channel": "self-serve",
        "region": "apac",
        "upsell-products": "alpha"
      },
    },
    { // Phase 2
      ...
      "metadata": {
        "channel": "sales",
        "churn-risk": "high",
        "upsell-products": ""
      },
    }
  ],
}

Quando essa programação cria uma assinatura e a assinatura inicia a Phase 1, as três chaves de metadados dessa fase são adicionadas aos metadados da assinatura. Portanto, os metadados da assinatura na Phase 1 são:

{
  ...
  "object": "subscription",
  "metadata": {
    "channel": "self-serve",
    "region": "apac",
    "upsell-products": "alpha"
  },
}

Quando a assinatura inicia a Phase 2, os metadados da assinatura são atualizados:

O valor de channel é atualizado porque o valor é especificado nos metadados da fase, e a assinatura já tem metadados com essa chave.
O valor de region não é alterado porque não é especificado na fase.
churn-risk é adicionado por ser uma nova chave.
A definição de upsell-products é cancelada porque um valor vazio é especificado na fase.

Portanto, os metadados da assinatura na Phase 2 são:

{
  ...
  "object": "subscription",
  "metadata": {
    "channel": "sales",
    "region": "apac",
    "churn-risk": "high"
  }
}

Saiba como copiar metadados de assinatura para faturas de assinatura.

Criar cronogramas de assinatura

A página de casos de uso tem exemplos mais completos. Veja a seguir um exemplo básico de como criar uma programação de assinatura usando um cliente. Quando uma programação é criada dessa forma, uma assinatura também é criada.

Observação

Ao contrário da criação direta de uma assinatura, a primeira fatura de uma programação de assinatura com collection_method definido como charge_automatically tem um comportamento de fatura recorrente e não é finalizada imediatamente no momento da criação da programação de assinatura. A fatura é criada com o status draft e é finalizada pela Stripe cerca de 1 hora após a criação.

Isso significa que, por exemplo, a criação de uma programação de assinatura com start_date=now também gera uma assinatura e uma fatura com o status draft. Dessa forma, você tem 1 hora para alterar a fatura. Posteriormente, o status muda automaticamente para open ou paid, dependendo do resultado da tentativa de pagamento assíncrono no momento da finalização.

Esta programação:

Inicia imediatamente após a criação.
Define a assinatura como uma instância do produto com o preço price_1GqNdGAJVYItwOKqEHb.
Realiza 12 iterações e exclui a assinatura da programação.

Também é possível criar programações de assinatura passando o ID da assinatura:

Uma assinatura criada dessa forma usa seus atributos para definir os atributos da programação.

Assim como em outras APIs da Stripe, você pode acessar e atualizar programações de assinatura. Também é possível cancelar e remover essas programações. O cancelamento da programação de uma assinatura também cancela a assinatura. Para remover a programação de uma assinatura, chame release.

Atualizar cronogramas de assinatura

Você somente pode atualizar as fases atuais e futuras em programações de assinatura.

É preciso passar todas as fases atuais e futuras ao atualizar um cronograma de assinatura. Você também precisa passar qualquer parâmetro definido anteriormente que deseja manter. Todos os parâmetros definidos anteriormente são cancelados para a fase existente, a menos que você os passe na solicitação de atualização. Você ainda recebe informações na resposta sobre as fases anteriores.

Você pode incluir até 10 fases atuais ou futuras. A atualização da fase ativa também atualiza a assinatura correspondente. Por exemplo, esta chamada mantém as datas de início e fim existentes, mas atualiza quantity nas duas:

Você também pode encerrar imediatamente a fase atual e iniciar uma nova fase. Nesse caso, a fase ativa passa para o passado e a nova fase é aplicada imediatamente à assinatura. O exemplo abaixo encerra a fase atual e inicia uma nova fase:

Para adicionar fases a uma programação de assinatura, passe a fase atual e defina as novas fases:

Ver a prévia de uma fatura

Use o parâmetro de agendamento em criar visualização para visualizar a próxima fatura de uma programação de assinatura.

Ver a prévia da criação e atualização de cronogramas

Use os parâmetros em schedule_details para visualizar a criação ou atualização de um cronograma de assinatura. Passe uma programação existente para informar à Stripe se é uma criação ou atualização.

Passe todas as fases atuais e futuras que você está visualizando.

Por exemplo, o código a seguir mostra a prévia da primeira fatura de um cronograma de assinatura com a fase 1 que tem 12 períodos de faturamento.

Outras considerações

Os cronogramas de assinatura geralmente seguem as mesmas restrições das assinaturas, mas também introduzem algumas restrições próprias. Além disso, a interação entre cronogramas de assinatura e assinaturas pode produzir comportamentos inesperados. Revise as seguintes seções para entender as limitações, o comportamento do produto e as práticas recomendadas gerais ao usar cronogramas de assinatura.

Restrições

Você só pode definir até 10 fases atuais ou futuras por vez em uma programação de assinatura. Fases passadas não contam para este limite.
As fases do cronograma de assinatura também seguem as mesmas restrições das assinaturas ao criar fases de um cronograma de assinatura com vários itens.

Limitações do Dashboard

Você pode criar e atualizar cronogramas de assinatura sem código no Dashboard.

No Dashboard, você pode definir as seguintes configurações globalmente em todas as fases, mas não por fase:

Limites de faturamento
Formas de pagamento
Configurações de fatura
Descrição da assinatura
Dias de avaliação (só funciona com a primeira fase)

Os seguintes parâmetros não são aceitos no Dashboard:

Metadados do cronograma de assinaturas
Metadados de item de fase
Moeda
Todos os parâmetros do Connect

A assinatura é atualizada quando um cronograma é vinculado

Use cronogramas de assinatura para modificar assinaturas automaticamente quando o tempo passar e a próxima fase do cronograma for inserida. Algumas alterações que você faz diretamente na assinatura são propagadas para as fases do cronograma da assinatura, mas outras não. Isso significa que qualquer modificação feita diretamente na assinatura poderá ser sobrescrita pelo cronograma da assinatura quando você entrar na próxima fase.

Quando programar alterações em uma assinatura, siga estas práticas recomendadas:

Se uma assinatura tiver um cronograma de assinatura vinculado, use a API Subscription Schedule para modificá-la, em vez da APISubscriptions.
Armazene os IDs do cronograma de assinatura junto com o ID da assinatura para futuras atualizações da API. O ID do cronograma de assinatura é retornado quando você usa a API para criá-lo ou por meio do webhook subscription_schedule.created quando a Stripe o cria automaticamente, como quando um cliente agenda um downgrade no Portal do cliente.
Descarte os IDs de cronogramas de assinatura quando um cronograma de assinatura for liberado. É possível fazer alterações diretamente nas assinaturas ou criar um cronograma de assinatura. O ID do cronograma de assinatura é retornado quando liberado com a API ou por meio do evento de webhook subscription_schedule quando o cronograma de assinatura é liberado.
Se possível, use o Dashboard para modificar assinaturas. Isso atualiza automaticamente qualquer cronograma de assinatura associado.

Especificamente, quando você altera qualquer um dos seguintes atributos de assinatura diretamente em uma assinatura, essa ação pode criar automaticamente uma nova fase de cronograma de assinatura:

discounts
tax_rates
items
trial_end, trial_settings, trial_start
application_fee_percent
add_invoice_items
automatic_tax

Por exemplo, considere uma assinatura com dois itens. A assinatura tem um cronograma de assinatura vinculado com uma única fase, refletindo o estado atual da assinatura. Se você usar a API para excluir um dos itens, a fase do cronograma de assinatura anexada será dividida automaticamente em duas fases:

A fase que acabou de terminar e tinha dois itens de assinatura
A nova fase que tem apenas um item na assinatura

Quando as fases do cronograma de assinatura são divididas automaticamente, as seguintes propriedades são copiadas da fase atual para a nova fase:

proration_behavior
billing_cycle_anchor
cancel_at_period_end
description
metadata
pause_collection

Além disso, a Stripe pode copiar os seguintes atributos de assinatura de nível superior para o cronograma de assinatura ou suas default_settings:

Atributo de assinatura	Copiado para a nova fase de cronograma de assinatura	Copiado para o cronograma de assinatura `default_settings`
`coupon`
`trial_end`
`tax_rates`
`application_fee_percent`
`discounts`
`collection_method`
`invoice_settings`
`default_payment_method`
`default_source`
`transfer_data`
`on_behalf_of`
`currency`
`add_invoice_items`
`automatic_tax`
`items.prices`
`billing_thresholds`

As atualizações dos metadata de uma assinatura não são propagadas para um cronograma de assinatura associado.

Veja também

Casos de uso da programação de assinaturas