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 quando ela alcança o end_date. No início de uma fase, a Stripe atualiza a assinatura de acordo com os atributos da fase seguinte. Você pode ativar cobranças proporcionais para creditar ao usuário itens ou tempo do plano não utilizados.

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

As programações de assinatura terminam após a conclusão da última fase. Nesse momento, a assinatura deixa de estar associada a uma programação e fica como está. Para cancelar uma assinatura após a conclusão da última fase de uma programação, defina end_behavior como cancel.

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.

Additional considerations

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 subscription schedules to modify subscriptions automatically when time passes and the schedule’s next phase is entered. Some changes that you make directly to the subscription propagate to the subscription schedule’s phases, but some don’t. This means that any modifications you make directly to the subscription might be overwritten by the subscription schedule when the next phase is entered.

When scheduling changes to a subscription, follow these best practices:

If a subscription has a subscription schedule attached, use the Subscription Schedule API to modify the subscription, instead of the Subscriptions API.
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.
Discard the subscription schedule IDs when a subscription schedule is released. You can make changes to the subscriptions directly or create a new subscription schedule. The subscription schedule ID is returned when released with the API or through the subscription_schedule.released webhook event when the subscription schedule releases.
Use the Dashboard to modify subscriptions, if possible, which automatically updates any attached subscription schedule.

Specifically, when you change any of the following subscription attributes directly on a subscription, this action might automatically create a new subscription schedule phase:

discounts
tax_rates
items
trial_end, trial_settings, trial_start
application_fee_percent
add_invoice_items
automatic_tax

For example, consider a subscription with two items. The subscription has a subscription schedule attached with a single phase, mirroring the current state of the subscription. If you use the API to delete one of the items, this automatically splits the attached subscription schedule’s phase into two phases:

The phase that just ended and had two subscription items
The new phase that has just one item on the subscription

When subscription schedule phases automatically split, the following properties are copied from the current phase to the new phase:

proration_behavior
billing_cycle_anchor
cancel_at_period_end
description
metadata
pause_collection

Additionally, Stripe might copy the following top-level subscription attributes to the subscription schedule or its default_settings:

Subscription attribute	Copied to new subscription schedule phase	Copied to subscription schedule `default_settings`
`coupon`	X
`trial_end`	X
`tax_rates`	X
`application_fee_percent`	X	X
`discounts`	X
`collection_method`	X	X
`invoice_settings`	X	X
`default_payment_method`	X	X
`default_source`	X	X
`transfer_data`	X	X
`on_behalf_of`	X	X
`billing_thresholds`	X	X
`currency`	X
`add_invoice_items`	X
`automatic_tax`	X	X
`items.prices`	X

Updates to subscription metadata aren’t propagated to an attached subscription schedule.

Veja também

Casos de uso da programação de assinaturas