Casos de uso para assinaturas programadas

Para entender a programação de assinaturas, 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 que isso aconteça, start_date é definido como uma data futura. Este código cria uma assinatura que começa no futuro:

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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

Atribuir uma data passada a 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 atribuição de uma data passada cobra pelo tempo já passado e permite que assinantes digitais acessem o site imediatamente.

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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, seus IDs podem ser passados 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 faturamento atual da assinatura.

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d from_subscription=
{{SUBSCRIPTION_ID}}

Enquanto adicionam essas programações, alguns clientes decidem obter uma assinatura impressa. Para isso, o Pacific adiciona uma segunda fase à programação para iniciar o plano de assinatura impressa daqui a um mês. Veja no caso de uso a seguir um exemplo desse processo.

Atualizar 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 avaliar antes a publicação impressa e depois decidir se desejam continuar ou cancelar a assinatura.

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 permite iniciar a assinatura como impressa e digital e depois fazer o downgrade para a publicação impressa pelo período restante da assinatura. Os clientes usam essa opção para avaliar os dois formatos.

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 decidem mudar para a opção básica com anúncios no próximo ciclo de faturamento. Crie uma programação usando a assinatura existente e atualize a programação com a opção básica com anúncios como uma nova fase.

# 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_4eC39HqLyjWDarjtT1zdp7dc'

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

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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

Às vezes, o Pacific oferece descontos de assinatura. Na programação abaixo, a assinatura do cliente começa com a publicação impressa com desconto de 50% por seis meses. A programação remove o cupom da assinatura na segunda fase, que abrange os seis meses restantes.

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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][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 de impostos

O Pacific opera em várias jurisdições. Algumas delas têm alíquotas exclusivas para negócios baseados em assinatura. Uma dessas jurisdições exige duas alíquotas: uma para o primeiro mês de assinatura do cliente e a outra para os faturamentos recorrentes.

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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

Cancelar uma assinatura de uma programação

Assinaturas com status not_started ou active podem ser removidas da programação. Uma assinatura removida continua como está, mas sai da programação e de todas as fases restantes.

curl -X POST https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}}
/release \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"

Cancelar uma programação e assinatura

É possível cancelar uma programação de assinatura e sua assinatura associada imediatamente (se a programação de assinatura tiver uma assinatura ativa). Uma programação de assinatura só pode ser cancelada se seu status for not_started ou active.

curl -X POST https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}}
/cancel \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"

Redefinir a âncora do ciclo de faturamento

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 faturamento 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 https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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:

curl https://api.stripe.com/v1/prices \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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.

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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:

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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