# Cronogramas de assinatura Saiba mais sobre os cronogramas de assinatura e como usá-los. Use [assinaturas programadas](https://docs.stripe.com/api/subscription_schedules.md) para automatizar alterações nas assinaturas ao longo do tempo. Você pode [criar](https://docs.stripe.com/api/subscription_schedules/create.md) assinaturas diretamente de uma programação ou adicionar uma programação a uma assinatura existente. Use o atributo [phases](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-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](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-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 Os cronogramas de assinatura estão disponíveis tanto no Stripe Billing Dashboard quanto na API. Para ver exemplos de como você pode usar cronogramas de assinatura, consulte [Casos de uso](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#use-cases). ## Fases Quando criar uma programação de assinatura, use o atributo [phases](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-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 programada em que a primeira fase dura três meses e contém o cupom de 50% de desconto. Na segunda fase, a assinatura volta ao custo normal e o cupom é removido. As fases devem ser sequenciais, o que significa que apenas uma fase pode estar ativa em um dado momento. Você pode ter até 10 fases. ### Defina a duração de uma fase Você pode definir a duração de uma fase usando a API ou o Dashboard. #### API As fases têm um atributo de [duração](https://docs.stripe.com/api/subscription_schedules/update.md#update_subscription_schedule-phases-duration) usado para especificar quanto tempo uma fase deve durar. O parâmetro `duration` aceita os seguintes valores: `week`, `month` ou `year`. A `end_date` de uma fase deve ser a `start_date` da próxima. O uso de `duration` define automaticamente `start_date` e `end_date` da forma correta. É possível definir esses valores manualmente, mas a Stripe recomenda usar a `duration`. Como a definição manual das datas de início e término está sujeita a erros, use-a apenas em casos de uso avançados. #### Dashboard Para definir a duração de uma fase: 1. No Dashboard, abra o [editor de assinatura](https://dashboard.stripe.com/subscriptions?create=subscription). 1. Adicione um novo cliente ou encontre um existente. 1. Adicione um novo produto ou encontre um existente. 1. Clique em **+ Adicionar fase**. 1. Selecione a duração da fase. Você também pode selecionar **Para sempre** para manter a assinatura ativa indefinidamente. ### 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](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-proration_behavior) 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: 1. **Agendar comportamento de cobrança proporcional de atualização**: O parâmetro [proration_behavior](https://docs.stripe.com/api/subscription_schedules/update.md#update_subscription_schedule-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). 1. **Comportamento de cobrança proporcional de transição de fase**: Cada fase tem seu próprio atributo [proration_behavior](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-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](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-proration_behavior) 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 um período de teste à primeira fase de uma assinatura usando a API ou o Dashboard. #### API Você pode adicionar períodos de avaliação definindo o [final da avaliação](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-trial_end) 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. #### Dashboard Para adicionar um período de teste à primeira fase de uma nova assinatura: 1. No Dashboard, abra o [editor de assinatura](https://dashboard.stripe.com/subscriptions?create=subscription). 1. Adicione um novo cliente ou encontre um existente. 1. Adicione um novo produto ou encontre um existente. 1. Em **Dias de teste gratuito**, defina a duração do período de teste gratuito. - Se você quiser que toda a fase seja um teste, defina a duração do teste igual à duração da fase. - Se você quiser que apenas parte da fase seja um teste, defina a duração do teste como mais curta do que a duração da fase. Para adicionar um período de teste à primeira fase de uma assinatura existente: 1. No Dashboard, acesse a página [Assinaturas](https://dashboard.stripe.com/subscriptions), selecione uma assinatura existente e clique em **Ações** > **Atualizar assinatura**. 1. Na assinatura, clique em **Editar** para a primeira fase. 1. Em **Dias de teste gratuito**, defina a duração do período de teste gratuito. - Se você quiser que toda a fase seja um teste, defina a duração do teste igual à duração da fase. - Se você quiser que apenas parte da fase seja um teste, defina a duração do teste como mais curta do que a duração da fase. 1. Clique em **Salvar** para atualizar a fase. 1. Clique em **Atualizar assinatura**. ### 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](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-end_behavior) como `cancel`. A [cancel_on_date](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-cancel_at) 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](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-default_settings-billing_thresholds) | [phases.billing_thresholds](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-billing_thresholds) | | [default_settings.collection_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-default_settings-collection_method) | [phases.collection_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-collection_method) | | [default_settings.default_payment_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-default_settings-default_payment_method) | [phases.default_payment_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-default_payment_method) | | [default_settings.invoice_settings](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-default_settings-invoice_settings) | [phases.invoice_settings](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-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. #### API Para usar metadados de fase com a API, defina [metadados (メタデータ)](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-metadata) 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: ```json { ... "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: ```json { ... "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: ```json { ... "object": "subscription", "metadata": { "channel": "sales", "region": "apac", "churn-risk": "high" } } ``` #### Dashboard Você pode adicionar, editar e remover entradas de metadados em cada fase do cronograma de uma assinatura usando o [editor de assinaturas do Dashboard do Billing](https://dashboard.stripe.com/subscriptions?create=subscription). Quando uma nova fase é ativada, os metadados do objeto de assinatura são atualizados para corresponder aos metadados dessa fase. 1. No Dashboard, abra o [editor de assinatura](https://dashboard.stripe.com/subscriptions?create=subscription). 1. Adicione um novo cliente ou encontre um existente. 1. Adicione um novo produto ou encontre um existente. 1. Em uma fase nova ou existente, clique em **+ Adicionar metadados**. 1. Insira uma **Chave** e um **Valor**, depois clique em **Salvar**. Saiba como [copiar metadados de assinatura para faturas de assinatura](https://docs.stripe.com/billing/invoices/subscription.md#subscription-metadata). ## Criar cronogramas de assinatura If your integration uses [customer-configured Accounts](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), replace `Customer` and event references in the code examples with the equivalent Accounts v2 API references. For more information, see [Represent customers with Account objects](https://docs.stripe.com/connect/use-accounts-as-customers.md). Este exemplo demonstra como criar uma programação de assinatura usando um cliente. Quando uma agenda é criada dessa forma, a assinatura também é criada. > 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 está* finalizada imediatamente no momento da criação da programação de assinatura. A fatura é criada com o status `draft` e finalizada pela Stripe [aproximadamente 1 hora após a criação](https://docs.stripe.com/billing/subscriptions/webhooks.md#understand). > > Por exemplo, quando você cria uma programação de assinatura com o método de cobrança definido para cobrar automaticamente e com `start_date=now`, uma assinatura também é criada e uma fatura com o status `draft`. Você tem 1 hora para [editar a fatura](https://docs.stripe.com/api/invoices/update.md). Posteriormente, a fatura avança automaticamente para o status `open` ou `paid`, dependendo do resultado da tentativa de pagamento assíncrono no momento da finalização. #### API ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d customer=cus_GBHHxuvBvO26Ea \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]=price_1GqNdGAJVYItwOKqEHb" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=12" ``` 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`. - Dura 12 meses e libera a assinatura do cronograma. Também é possível criar programações de assinatura passando o ID da assinatura: ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d from_subscription=sub_GB98WOvaRAWPl6 ``` 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 os [cronogramas de assinatura](https://docs.stripe.com/api/subscription_schedules.md). Também é possível cancelar e remover esses cronogramas. Se você quiser apenas remover um cronograma de uma assinatura, use a chamada de [liberação](https://docs.stripe.com/api/subscription_schedules/release.md). #### Dashboard Para criar cronogramas de assinatura de várias fases: 1. No Dashboard, abra o [editor de assinatura](https://dashboard.stripe.com/subscriptions?create=subscription). 1. Adicione um novo cliente ou encontre um existente. 1. Adicione um novo produto ou encontre um existente. 1. Defina uma duração para a primeira fase do cronograma de assinatura. 1. Clique em **+ Adicionar fase**. 1. Selecione a duração da fase. Você também pode selecionar **Para sempre** para manter a assinatura ativa indefinidamente. 1. 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 período de cobrança, 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. 1. Salve a nova fase. 1. Adicione quaisquer fases adicionais conforme necessário. 1. Clique em **Agendar assinatura**. ## Atualizar cronogramas de assinatura Você somente pode atualizar as fases atuais e futuras em programações de assinatura. #### API É 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 atualiza `quantity` para dois: ```curl curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}} \ -u "<>:" \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=2" \ -d "phases[0][start_date]=1577865600" \ -d "phases[0][end_date]=1580544000" ``` 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: ```curl curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}} \ -u "<>:" \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][start_date]=1577865600" \ -d "phases[0][end_date]=now" \ -d "phases[1][items][0][price]={{PRICE_ID}}" \ -d "phases[1][items][0][quantity]=2" \ -d "phases[1][start_date]=now" \ -d "phases[1][end_date]=1580544000" ``` Para adicionar fases a uma programação de assinatura, passe a fase atual e defina as novas fases: ```curl curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}} \ -u "<>:" \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][start_date]=1577865600" \ -d "phases[0][end_date]=1580544000" \ -d "phases[1][items][0][price]={{PRICE_ID}}" \ -d "phases[1][items][0][quantity]=2" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=1" ``` #### Dashboard Para atualizar assinaturas existentes e ter fases de cronograma de assinatura futuras: 1. No Dashboard, acesse a página [Assinaturas](https://dashboard.stripe.com/subscriptions), selecione uma assinatura existente e clique em **Ações** > **Atualizar assinatura**. 1. Defina uma duração para a fase atual do cronograma de assinatura selecionando uma data final. 1. Clique em **+ Adicionar fase**. 1. Selecione a duração da próxima fase. Você também pode selecionar **Para sempre** para manter a assinatura ativa indefinidamente. 1. 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 período de cobrança, 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. 1. Salve a nova fase. 1. Adicione quaisquer fases adicionais conforme necessário. 1. Clique em **Agendar assinatura**. ## Ver a prévia de uma fatura Use o parâmetro de [agendamento](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule) em [criar visualização](https://docs.stripe.com/api/invoices/create_preview.md) para visualizar a próxima fatura de uma programação de assinatura. ```curl curl https://api.stripe.com/v1/invoices/create_preview \ -u "<>:" \ -d "schedule={{SUBSCRIPTIONSCHEDULE_ID}}" ``` ### Ver a prévia da criação e atualização de cronogramas Use os parâmetros em [schedule_details](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule_details) para visualizar a criação ou atualização de um cronograma de assinatura. Passe uma [programação](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule) existente para informar à Stripe se é uma criação ou atualização. Passe todas as [fases](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule_details-phases) atuais e futuras que você está visualizando. Por exemplo, o código a seguir exibe uma prévia da primeira fatura de um cronograma de assinatura com a fase `1` que tem `12` meses de duração. ```curl curl https://api.stripe.com/v1/invoices/create_preview \ -u "<>:" \ -d "customer_details[address][line1]=920 5th Ave" \ -d "customer_details[address][city]=Seattle" \ -d "customer_details[address][state]=WA" \ -d "customer_details[address][postal_code]=98104" \ -d "customer_details[address][country]=US" \ -d "schedule_details[phases][0][start_date]=now" \ -d "schedule_details[phases][0][items][0][price]={{PRICE_ID}}" \ -d "schedule_details[phases][0][items][0][quantity]=1" \ -d "schedule_details[phases][0][duration][interval]=month" \ -d "schedule_details[phases][0][duration][interval_count]=12" ``` ## 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](https://docs.stripe.com/billing/subscriptions/quantities.md#billing-periods-with-multiple-prices) ao criar fases do cronograma de assinatura com vários itens. ### Limitações do Dashboard Você pode criar e atualizar cronogramas de assinatura sem código no [Dashboard](https://dashboard.stripe.com/test/subscriptions). 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](https://docs.stripe.com/api/subscription_schedules.md) 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](https://docs.stripe.com/api/subscription_schedules.md) para modificá-la, em vez da API[Subscriptions](https://docs.stripe.com/api/subscriptions.md#subscriptions). - 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](https://docs.stripe.com/api/subscription_schedules/create.md) ou por meio do [webhook subscription_schedule](https://docs.stripe.com/api/events/types.md#event_types-subscription_schedule.created).created quando a Stripe o cria automaticamente, como quando um cliente agenda um downgrade no [Portal do cliente](https://docs.stripe.com/customer-management/configure-portal.md#configure-subscription-management). - 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](https://docs.stripe.com/api/subscription_schedules/release.md) ou por meio do evento de webhook [subscription_schedule](https://docs.stripe.com/api/events/types.md#event_types-subscription_schedule.released) 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](https://docs.stripe.com/api/subscription_items/delete.md) um dos itens, a fase do cronograma de assinatura anexada será dividida automaticamente em duas fases: 1. A fase que acabou de terminar e tinha dois itens de assinatura 1. 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`](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-default_settings): | Atributo de assinatura | Copiado para a nova fase de cronograma de assinatura | Copiado para o cronograma de assinatura `default_settings` | | ------------------------- | ---------------------------------------------------- | ---------------------------------------------------------- | | `coupon` | ✓ Supported | - Unsupported | | `trial_end` | ✓ Supported | - Unsupported | | `tax_rates` | ✓ Supported | - Unsupported | | `application_fee_percent` | ✓ Supported | ✓ Supported | | `discounts` | ✓ Supported | - Unsupported | | `collection_method` | ✓ Supported | ✓ Supported | | `invoice_settings` | ✓ Supported | ✓ Supported | | `default_payment_method` | ✓ Supported | ✓ Supported | | `default_source` | ✓ Supported | ✓ Supported | | `transfer_data` | ✓ Supported | ✓ Supported | | `on_behalf_of` | ✓ Supported | ✓ Supported | | `currency` | ✓ Supported | - Unsupported | | `add_invoice_items` | ✓ Supported | - Unsupported | | `automatic_tax` | ✓ Supported | ✓ Supported | | `items.prices` | ✓ Supported | - Unsupported | | `billing_thresholds` | ✓ Supported | ✓ Supported | As atualizações dos `metadata` de uma assinatura não são propagadas para um cronograma de assinatura associado. ## Casos de uso Para entender as programações de assinatura, vamos imaginar um jornal fictício, The Pacific, que oferece duas opções de assinatura: - *Impressa*: os clientes recebem o jornal físico - *Digital*: os clientes recebem acesso ao conteúdo exclusivo do site do Pacific As duas assinaturas são cobradas mensalmente. Examine abaixo as opções de programações de assinatura possíveis. ### Iniciar uma assinatura no futuro Por padrão, as novas assinaturas impressas começam no primeiro dia do próximo mês. Para fazer isso, defina a `start_date` para um ponto no futuro. O código abaixo cria uma assinatura que começa no futuro: ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=1690873200 \ -d end_behavior=release \ -d "phases[0][items][0][price]={{PRICE_PRINT}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=12" ``` ### Definir data retroativa para uma assinatura Quando os clientes assinam o plano digital, o Pacific define a data de início como o primeiro dia do mês atual. A definição de data retroativa permite que você cobre por tempo no passado e permite que assinantes digitais acessem o site imediatamente. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=1688194800 \ -d end_behavior=release \ -d "phases[0][items][0][price]={{PRICE_DIGITAL}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=12" ``` ### Adicionar uma programação a uma assinatura existente O Pacific pode constatar que alguns clientes originais têm assinaturas sem programação. Como essas assinaturas já existem, você pode passar os IDs de assinatura no atributo `from_subscription` para adicionar uma programação. A passagem de IDs de assinatura dessa forma cria uma programação com uma fase, baseada no período de cobrança atual da assinatura. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "from_subscription={{SUBSCRIPTION_ID}}" ``` Enquanto adicionam essas programações, alguns clientes decidem obter uma assinatura impressa. Portanto, o Pacific adiciona uma segunda fase à programação para iniciar o plano de assinatura impressa daqui a um mês. O caso de uso [Atualizar assinaturas](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#upgrading-subscriptions) mostra um exemplo desse processo. ### Fazer upgrade de assinaturas O Pacific oferece uma opção de início de assinatura impressa por um mês com adição automática da assinatura digital a partir do segundo mês. Alguns clientes preferem essa opção porque podem tentar primeiro a publicação impressa e depois decidir se desejam continuar ou cancelar a assinatura. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]={{PRICE_PRINT}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=1" \ -d "phases[1][items][0][price]={{PRICE_PRINT}}" \ -d "phases[1][items][0][quantity]=1" \ -d "phases[1][items][1][price]={{PRICE_DIGITAL}}" \ -d "phases[1][items][1][quantity]=1" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=11" ``` ### Fazer downgrade de assinaturas O Pacific também oferece uma opção de início de assinatura impressa e digital com downgrade para a publicação impressa pelo período restante da assinatura. Os *clientes* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) usam essa opção para experimentar as duas publicações e ver como gostam. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]={{PRICE_DIGITAL}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][items][1][price]={{PRICE_PRINT}}" \ -d "phases[0][items][1][quantity]=1" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=1" \ -d "phases[1][items][0][price]={{PRICE_PRINT}}" \ -d "phases[1][items][0][quantity]=1" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=11" ``` ### Alterar assinaturas A Pacific oferece duas opções de assinatura impressa, uma opção básica com anúncios ou uma opção premium sem anúncios. Alguns clientes na opção premium querem mudar para a opção básica com anúncios no próximo período de cobrança. Você pode criar uma programação usando a assinatura existente e então atualizar a programação com a opção básica com anúncios como uma nova fase. #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. Stripe.api_key = '<>' # Create a subscription schedule with the existing subscription schedule = Stripe::SubscriptionSchedule.create({ from_subscription: 'sub_ERf72J8Sc7qx7D', }) # Update the schedule with the new phase Stripe::SubscriptionSchedule.update( schedule.id, { phases: [ { items: [ { price: schedule.phases[0].items[0].price, quantity: schedule.phases[0].items[0].quantity, }, ], start_date: schedule.phases[0].start_date, end_date: schedule.phases[0].end_date, }, { items: [ { price: '{{PRICE_PRINT_BASIC}}', quantity: 1, }, ], duration: { interval: 'month', interval_count: 1, }, }, ], }, ) ``` ### Aumentar a quantidade Você também pode agendar aumentos das quantidades de uma assinatura. A programação abaixo começa com uma instância da publicação digital por um mês. Na segunda fase, a quantidade é aumentada para 2 por mais 11 meses. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=1" \ -d "phases[1][items][0][price]={{PRICE_ID}}" \ -d "phases[1][items][0][quantity]=2" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=11" ``` ### Usar cupons O Pacific ocasionalmente oferece descontos de assinatura. A programação abaixo inicia a publicação impressa com desconto de 50% por seis meses. A programação remove o cupom da assinatura na segunda fase pelos seis meses restantes. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=6" \ -d "phases[0][discounts][0][coupon]={{COUPON_ID}}" \ -d "phases[1][items][0][price]={{PRICE_ID}}" \ -d "phases[1][items][0][quantity]=1" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=6" ``` ### Alterar alíquotas O Pacific opera em várias jurisdições e algumas têm alíquotas exclusivas para empresas que trabalham com assinaturas. Uma dessas jurisdições exige duas alíquotas: uma para o primeiro mês de assinatura do cliente e a outra para cobranças recorrentes. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][items][0][tax_rates][0]=txr_2J8lmBBGHJYyuUJqF6QJtaAA" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=1" \ -d "phases[1][items][0][price]={{PRICE_ID}}" \ -d "phases[1][items][0][quantity]=1" \ -d "phases[1][items][0][tax_rates][0]=txr_2J8lmBBGHJYyuUJqF6QJtbBB" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=11" ``` ### Remover uma assinatura da programação Você pode [remover](https://docs.stripe.com/api/subscription_schedules/release.md) uma assinatura de uma programação se o status for `not_started` ou `active`. Uma assinatura removida continua como está, mas remove o cronograma e todas as fases restantes. ```curl curl -X POST https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}}/release \ -u "<>:" ``` ### Cancelar uma programação e uma assinatura Se uma programação de assinatura tiver uma assinatura ativa, você poderá cancelá-la e a assinatura associada imediatamente. Só é possível cancelar uma programação de assinatura se o status for `not_started` ou `active`. ```curl curl -X POST https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}}/cancel \ -u "<>:" ``` ### Redefinir a âncora do ciclo de cobrança O Pacific fatura os clientes de longa data da publicação impressa no mesmo dia do mês em que iniciaram a assinatura. Esse dia é a âncora do ciclo de faturamento. Se esses clientes mudam para a edição digital, o Pacific agenda a data de transição para o 1º dia do mês seguinte. Além disso, a âncora do ciclo de faturamento é redefinida para essa mesma data. Você pode verificar se a âncora do ciclo de cobrança foi redefinida criando uma assinatura com o exemplo de código abaixo. Observe a assinatura no Dashboard e veja que a próxima fatura está agendada para cobrar o cliente no início da assinatura digital, no dia 1º. Para ver o que acontece quando você não redefine a âncora, execute o exemplo de código exemplo novamente, mas remova a linha que define a âncora do ciclo de faturamento em `phase_start`. Sem essa linha, a próxima fatura mostrada no Dashboard está agendada para faturar o cliente em até um mês a partir de hoje, apesar da transição no dia 1º. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d "phases[0][items][0][price]={{PRICE_PRINT}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][end_date]=1690873200" \ -d "phases[1][items][0][price]={{PRICE_DIGITAL}}" \ -d "phases[1][items][0][quantity]=1" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=11" \ -d "phases[1][billing_cycle_anchor]=phase_start" ``` ### Planos parcelados Os planos parcelados permitem que os clientes façam pagamentos parciais por um determinado período até que o valor total seja pago. Por exemplo, quando o Pacific compra novas impressoras rotativas, vende as impressoras usadas para outras publicações. Publicações menores dificilmente têm fundos suficientes para pagar antecipadamente uma impressora rotativa e pagam usando um plano parcelado. Para a maioria das impressoras, o Pacific cobra US$ 1.000 por mês. Logo, é criado um preço reutilizável: ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d unit_amount=100000 \ -d currency=usd \ -d product=prod_Hh99apo1OViyGW \ -d "recurring[interval]=month" ``` O Pacific cobra valores diferentes de acordo com a marca, modelo e tempo de uso da impressora. Este exemplo cobra US$ 1.000 por mês durante 6 meses, totalizando US$ 6.000. #### Contas v2 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d start_date=now \ -d end_behavior=cancel \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][iterations]=6" ``` #### Clientes v1 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=cancel \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][iterations]=6" ``` O número de `iterations` é multiplicado pelo intervalo do preço (neste exemplo, 6 pagamentos mensais) para determinar o número de cobranças do cliente. `end_behavior` determina o que acontece com a assinatura após a conclusão da última iteração. Em um plano parcelado, a assinatura não é mais necessária. Portanto, `end_behavior` é definido como `cancel`. Muito raramente, o Pacific cobra menos do que os US$ 1.000 habituais por mês. Nesses casos, a empresa usa `price_data` para criar um preço de uso único. Este exemplo cria um preço de US$ 500 e cobra mensalmente por 6 meses: #### Contas v2 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d start_date=now \ -d end_behavior=cancel \ -d "phases[0][items][0][price_data][currency]=usd" \ -d "phases[0][items][0][price_data][product]=prod_Hh99apo1OViyGW" \ -d "phases[0][items][0][price_data][recurring][interval]=month" \ -d "phases[0][items][0][price_data][unit_amount]=50000" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][iterations]=6" ``` #### Clientes v1 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=cancel \ -d "phases[0][items][0][price_data][currency]=usd" \ -d "phases[0][items][0][price_data][product]=prod_Hh99apo1OViyGW" \ -d "phases[0][items][0][price_data][recurring][interval]=month" \ -d "phases[0][items][0][price_data][unit_amount]=50000" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][iterations]=6" ```