Cronogramas de assinatura
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.
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:
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.
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.
Criar cronogramas de assinatura sem código
Você pode criar agendamentos de assinatura com várias fases sem usar código no editor de assinatura do Stripe Billing. Para fazer isso, siga estas etapas:
- No Dashboard, abra o editor de assinatura.
- Adicione um cliente.
- Adicione um preço à lista suspensa de seleção de produtos.
- Defina uma duração para a primeira fase do cronograma de assinatura.
- Clique em + Adicionar fase.
- Selecione a próxima duração de fase ou apenas vitalícia para manter a assinatura.
- Faça as alterações necessárias na nova fase. Você pode alterar a quantidade e o preço, adicionar ou remover cupons, redefinir a data do ciclo de faturamento, alterar o comportamento de cobranças proporcionais ou atualizar metadados. Se você alterar os metadados em uma fase, os metadados da assinatura serão atualizados quando essa fase for ativada.
- Salve a nova fase.
- Adicione quaisquer fases adicionais conforme necessário.
- Crie uma assinatura.
Atualizar cronogramas de assinatura
Você só pode atualizar as fases atuais e futuras em cronogramas 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:
Atualizar cronogramas de assinatura sem código
Você pode atualizar assinaturas existentes para ter fases de cronograma de assinatura futuras usando o editor de assinatura do Stripe Billing. Para fazer isso, siga estas etapas:
- No Dashboard, acesse a página Assinaturas, selecione uma assinatura existente e clique em Ações > Atualizar assinatura.
- Defina uma duração para a fase atual do cronograma de assinatura selecionando uma data final.
- Clique em + Adicionar fase.
- Selecione a próxima duração de fase ou selecione vitalícia para manter a assinatura.
- Faça as alterações necessárias na nova fase. Você pode alterar a quantidade e o preço, adicionar ou remover cupons, redefinir a data do ciclo de faturamento, alterar o comportamento de cobranças proporcionais ou atualizar metadados. Se você alterar os metadados em uma fase, os metadados da assinatura serão atualizados quando essa fase for ativada.
- Salve a nova fase.
- Adicione quaisquer fases adicionais conforme necessário.
- Crie uma assinatura.
Ver a prévia de uma fatura
Use o parâmetro schedule na API upcoming invoice para ver a prévia da próxima fatura de um cronograma de assinatura.
Ver a prévia da criação e atualização de cronogramas
Use os parâmetros em schedule_details para ver a prévia da criação ou atualização de um cronograma de assinatura. Passe um cronograma existente para informar à Stripe se é uma criação ou atualização.
Passe todas as fases 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.
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