# 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 usar cronogramas de assinaturas, consulte [Casos de uso](https://docs.stripe.com/billing/subscriptions/subscription-schedules/use-cases.md). ## 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). 2. Adicione um novo cliente ou encontre um existente. 3. Adicione um novo produto ou encontre um existente. 4. Clique em **+ Adicionar fase**. 5. 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). 2. **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 assinaturas](https://dashboard.stripe.com/subscriptions?create=subscription). 2. Adicione um novo cliente ou encontre um existente. 3. Adicione um novo produto ou encontre um existente. 4. 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. 5. Clique em **Criar assinatura**. 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**. 2. Na assinatura, clique em **Editar** para a primeira fase. 3. 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. 4. 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.automatic_tax](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-default_settings-automatic_tax) | [phases.automatic_tax](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-automatic_tax) | | [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 | ### Configure impostos para cada fase A configuração [automatic_tax](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-automatic_tax) de uma fase substitui a [default_settings.automatic_tax](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-default_settings-automatic_tax) do cronograma. Se você omitir `automatic_tax` em uma fase, ela herdará a configuração padrão do cronograma. Para usar [default_tax_rates](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-default_tax_rates) manuais em uma fase, defina `automatic_tax.enabled` dessa fase como `false`. Isso impedirá que a fase herde o imposto automático habilitado se o padrão do cronograma mudar mais tarde. Não é possível configurar alíquotas de imposto manuais e habilitar o imposto automático para a mesma fase, independentemente de você ter habilitado o imposto automático na fase ou de ele ter sido herdado do cronograma. Para usar o imposto automático, remova as alíquotas de imposto manuais da fase ao habilitá-lo. Se você habilitar o imposto automático diretamente em uma assinatura com um cronograma associado, a Stripe atualizará a fase atual e a configuração de imposto automático padrão do cronograma. As fases futuras mantêm sua configuração, mas as fases sem uma configuração `automatic_tax` explícita herdam o padrão atualizado. Por exemplo, se uma fase futura retiver `default_tax_rates` e herdar o imposto automático habilitado, o imposto automático tem precedência e a Stripe não usa essas alíquotas manuais para calcular o imposto. As alíquotas retidas não serão uma alternativa se o cálculo do imposto automático falhar. ### 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). 2. Adicione um novo cliente ou encontre um existente. 3. Adicione um novo produto ou encontre um existente. 4. Em uma fase nova ou existente, clique em **+ Adicionar metadados**. 5. 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 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 > #### Use a API Accounts v2 para representar clientes > > A API Accounts v2 está geralmente disponível para usuários do Connect e em prévia pública para outros usuários da Stripe. Se faz parte da prévia de Accounts v2, é necessário [especificar uma versão de prévia](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) no seu código. > > Para participar da prévia de Accounts v2, acesse [Prévias e recursos da conta](https://dashboard.stripe.com/settings/previews) no Dashboard e ative **Formas de pagamento reutilizáveis para Global Payouts**. > > Para a maioria dos casos de uso, recomendamos [modelar seus clientes como objetos Accounts configuradas pelo cliente](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md), em vez de usar objetos [Customer](https://docs.stripe.com/api/customers.md). #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -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" ``` #### Customers v1 ```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_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={{SUBSCRIPTION_ID}}" ``` 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). 2. Adicione um novo cliente ou encontre um existente. 3. Adicione um novo produto ou encontre um existente. 4. Defina uma duração para a primeira fase do cronograma de assinatura. 5. Clique em **+ Adicionar fase**. 6. Selecione a duração da fase. Você também pode selecionar **Para sempre** para manter a assinatura ativa indefinidamente. 7. 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. 8. Salve a nova fase. 9. Adicione quaisquer fases adicionais conforme necessário. 10. Clique em **Agendar assinatura**. ## Atualizar cronogramas de assinatura Você somente pode atualizar as fases atuais e futuras em programações de assinatura. Um upgrade ou downgrade é uma atualização de assinatura que altera o nível de uma assinatura substituindo seu preço. Outras atualizações de cronograma podem alterar quantidades, descontos ou datas das fases sem alterar os níveis. Para ver detalhes da API sobre substituição de preço e atualização de assinatura, consulte [Alterar o preço de assinaturas existentes](https://docs.stripe.com/billing/subscriptions/change-price.md). #### 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**. 2. Defina uma duração para a fase atual do cronograma de assinatura selecionando uma data de término. Para agendar um upgrade ou downgrade, mantenha o preço existente da fase atual até essa data. 3. Clique em **+ Adicionar fase**. 4. Selecione a duração da próxima fase. Você também pode selecionar **Para sempre** para manter a assinatura ativa indefinidamente. 5. 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. Para um upgrade ou downgrade, substitua o preço do nível antigo pelo preço do nível desejado nesta fase futura. Mantenha quaisquer itens de assinatura não relacionados e defina as quantidades adequadas. Não mantenha os preços dos dois níveis na mesma fase, a menos que pretenda cobrar por ambos. 6. Salve a nova fase. 7. Adicione quaisquer fases adicionais conforme necessário. 8. Clique em **Agendar assinatura**. ## Ver a prévia de uma fatura Você pode ver a prévia da próxima fatura de um cronograma de assinatura usando a API ou o Dashboard. #### API 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" ``` #### Dashboard Depois que o cronograma de assinatura começar, você pode ver a prévia da próxima fatura na página da assinatura: 1. No Dashboard, acesse a página [Assinaturas](https://dashboard.stripe.com/subscriptions) e selecione a assinatura associada ao cronograma. 2. Revise a seção **Próxima fatura**. ## 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. ### Limitaçõ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 em uma fase individual: - 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 no nível do cronograma de assinatura ([metadata](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-metadata)): pares chave-valor que você pode anexar ao objeto Cronograma de assinatura. - Metadados do item da fase ([phases.items.metadata](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-items-metadata)): pares chave-valor que você pode anexar a um item de configuração. - Moeda ([phases.currency](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-currency)): a moeda usada para uma fase. - Todos os parâmetros do Connect: o Dashboard não aceita parâmetros exclusivos do Connect, como [phases.on_behalf_of](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-on_behalf_of) ou [phases.application_fee_percent](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-application_fee_percent). ### 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 2. 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` | ✓ Aceito | - Não aceito | | `trial_end` | ✓ Aceito | - Não aceito | | `tax_rates` | ✓ Aceito | - Não aceito | | `application_fee_percent` | ✓ Aceito | ✓ Aceito | | `discounts` | ✓ Aceito | - Não aceito | | `collection_method` | ✓ Aceito | ✓ Aceito | | `invoice_settings` | ✓ Aceito | ✓ Aceito | | `default_payment_method` | ✓ Aceito | ✓ Aceito | | `default_source` | ✓ Aceito | ✓ Aceito | | `transfer_data` | ✓ Aceito | ✓ Aceito | | `on_behalf_of` | ✓ Aceito | ✓ Aceito | | `currency` | ✓ Aceito | - Não aceito | | `add_invoice_items` | ✓ Aceito | - Não aceito | | `automatic_tax` | ✓ Aceito | ✓ Aceito | | `items.prices` | ✓ Aceito | - Não aceito | | `billing_thresholds` | ✓ Aceito | ✓ Aceito | As atualizações dos `metadata` de uma assinatura não são propagadas para um cronograma de assinatura associado.