Pular para o conteúdo
Criar conta
 ou
Entrar
O logotipo da documentação da Stripe
/
Criar conta
Login
Visão geral
Billing
Visão geralSobre as APIs do Billing
Tributos
Visão geral
Relatórios
Visão geralRelatórios para várias contas
Dados
Visão geralEsquema

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 vídeo mostra como funcionam os cronogramas de assinatura no Dashboard:

Cronogramas de assinatura no Dashboard

Para ver exemplos de como você pode usar cronogramas de assinatura, consulte 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 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.

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

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

Transição para a próxima fase

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

Comportamento da cobrança proporcional

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

  1. Agendar comportamento de cobrança proporcional de atualização: O parâmetro proration_behavior de nível superior controla como gerenciar cobranças proporcionais durante a atualização de um cronograma de assinatura de uma maneira que afeta a configuração de cobrança da fase atual (como alterar preços ou quantidades).

  2. Comportamento de cobrança proporcional de transição de fase: Cada fase tem seu próprio atributo proration_behavior que controla como a Stripe lida com cobranças proporcionais durante a transição para essa fase.

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

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

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

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

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

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

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

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

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

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

Usar avaliações

Você pode adicionar um período de teste à primeira fase de uma assinatura usando a API ou o Dashboard.

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

Concluir um cronograma

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

Herança de atributos de fase

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

Atributo de programaçãoAtributo de fase
default_settings.billing_thresholdsphases.billing_thresholds
default_settings.collection_methodphases.collection_method
default_settings.default_payment_methodphases.default_payment_method
default_settings.invoice_settingsphases.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 presenteAtributo da fase presenteResultado
NãoNãoAssume o valor padrão das configurações do cliente ou da conta
SimNãoAtributo da programação definido
SimSimAtributo da fase definido
NãoSimAtributo 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

Este exemplo demonstra como criar uma programação de assinatura usando um cliente. Quando uma agenda é criada dessa forma, a 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 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.

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. 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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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][iterations]"=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.
  • 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:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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 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:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}}
 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}}
 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}}
 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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][iterations]"=1

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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d schedule=
{{SUBSCRIPTION_SCHEDULE_ID}}

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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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][iterations]"=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 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.

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

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

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

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

A assinatura é atualizada quando um cronograma é vinculado

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

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

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

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

  • discounts
  • tax_rates
  • items
  • trial_end, trial_settings, trial_start
  • application_fee_percent
  • add_invoice_items
  • automatic_tax

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

  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:

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

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

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:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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][iterations]"=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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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][iterations]"=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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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 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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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][iterations]"=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][iterations]"=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 usam essa opção para experimentar as duas publicações e ver como gostam.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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][iterations]"=1 \
  -d "phases[1][items][0][price]"={{PRICE_PRINT}} \
  -d "phases[1][items][0][quantity]"=1 \
  -d "phases[1][iterations]"=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.

server.rb
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


# 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,
          },
        ],
        iterations: 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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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][iterations]"=1 \
  -d "phases[1][items][0][price]"=
{{PRICE_ID}}
 \
  -d "phases[1][items][0][quantity]"=2 \
  -d "phases[1][iterations]"=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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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][iterations]"=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][iterations]"=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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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][iterations]"=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][iterations]"=11

Remover uma assinatura da programação

Você pode remover 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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}}
/release \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}}
/cancel \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

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º.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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][iterations]"=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:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/prices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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
Esta página foi útil?
SimNão