Casos de uso de calendarios de suscripciones

Para entender los calendarios de suscripciones, imaginemos la empresa de un diario ficticio llamada The Pacific. Ofrece dos opciones de suscripción:

• Versión impresa, los clientes reciben la versión en papel
• Versión digital, los clientes acceden a contenido exclusivo del sitio web de The Pacific

Ambas suscripciones se facturan mensualmente. Examina las posibles opciones de calendarios de suscripciones a continuación.

Iniciar una suscripción en el futuro

En forma predeterminada, las nuevas suscripciones a la versión impresa comienzan el primer día del mes siguiente. Para ello, se establece start_date en un punto en el futuro. En el siguiente código, se crea una suscripción que comienza en el 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

Antedatar una suscripción

Cuando los clientes se suscriben al plan digital, The Pacific antedata sus suscripciones al primer día del mes en curso. Al antedatar los cargos a una fecha pasada, se les permite a los suscriptores acceder al sitio web de inmediato.

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

Agregar un calendario a una suscripción existente

Supongamos que The Pacific descubre que algunos de sus primeros clientes tienen suscripciones sin calendarios. Puesto que estas suscripciones ya existen, se pueden establecer los ID de las suscripciones en el atributo from_subscription para agregar un calendario. La especificación del ID de esta manera crea un calendario con una fase basada en el período de facturación actual de la suscripción.

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

Mientras se agregan estos calendarios, algunos clientes deciden pedir una suscripción a la versión impresa, de modo que The Pacific agrega una segunda fase al calendario para iniciar el plan de suscripción a la versión impresa de aquí a un mes. El siguiente caso de uso muestra un ejemplo de este proceso.

Cambiar suscripciones a un plan superior

The Pacific ofrece una opción para empezar con una suscripción a la versión impresa por un mes y luego agregar automáticamente la opción digital. Algunos clientes la prefieren porque pueden probar la publicación impresa primero y decidir luego si quieren continuar con la suscripción o cancelarla.

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

Cambiar suscripciones a un plan inferior

The Pacific also offers an option to start a subscription with both the print and digital publications, and then downgrade to only the print publication for the rest of the subscription. Customers use this option to test out both publications to see how they like them.

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

Cambiar suscripciones

The Pacific ofrece dos opciones de suscripción impresa, una opción básica con anuncios o una opción premium sin anuncios. Algunos clientes en la opción premium deciden que quieren cambiar a la opción básica con anuncios en el próximo ciclo de facturación. Crea una programación utilizando la suscripción existente y luego actualiza la programación con la opción básica con anuncios como una nueva 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 la cantidad

En la suscripción, también puedes programar aumentos en la cantidad. El siguiente calendario comienza con una instancia de la publicación digital por un mes. En la segunda fase, la cantidad se incrementa a 2 por 11 meses más.

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 cupones

A veces, The Pacific ofrece suscripciones especiales. El calendario a continuación comienza con una publicación impresa al 50 % por seis meses. El calendario elimina el cupón de la suscripción en la segunda fase, que comprende los 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

Cambiar tasas impositivas

The Pacific opera en varias jurisdicciones, y algunas de ellas tienen tasas impositivas exclusivas para las empresas que ofrecen suscripciones. Una de estas jurisdicciones requiere dos tasas impositivas: una para el primer mes en que se suscribe el cliente y otra para las facturas recurrentes.

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

Liberar una suscripción de un calendario

Puedes liberar una suscripción de un calendario siempre y cuando el estado del calendario sea not_started o active. Liberar una suscripción no significa eliminarla, sino eliminar el calendario y todas las fases restantes.

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

Cancelar un calendario y una suscripción

Puedes cancelar un calendario de suscripciones y su suscripción asociada de inmediato (si el calendario de suscripciones tiene una suscripción activa). Un calendario de suscripciones solo se puede cancelar si su estado es not_started o active.

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

Restablecer la delimitación del ciclo de facturación

The Pacific les factura a sus antiguos suscriptores a la publicación impresa en el día del mes en el que se suscribieron originalmente. Ese día es el delimitador del ciclo de facturación.

Cuando los clientes pasan a la edición digital, The Pacific programa la fecha de transición para el primer día del mes siguiente. También restablece la delimitación del ciclo de facturación a la misma fecha.

Puedes verificar si se restablece la delimitación del ciclo de facturación creando una suscripción con el código de ejemplo que aparece abajo. Mira la suscripción en el Dashboard y observa que la próxima factura está programada para cobrarle al cliente tan pronto como inicie la suscripción a la versión digital, el día 1.

Para ver qué pasaría si no restablecieras la delimitación, vuelve a ejecutar el código de ejemplo, pero esta vez elimina la línea que establece la delimitación del ciclo de facturación en phase_start. Sin esta línea, la función Próxima factura en el Dashboard espera un mes, a partir de hoy, para facturarle al cliente, a pesar de que la transición tiene lugar el día 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

Planes de cuotas

Los planes de cuotas les dan a los clientes la posibilidad de hacer pagos parciales por una determinada cantidad de tiempo hasta saldar el importe total. Por ejemplo, The Pacific compra imprentas nuevas y vende las usadas a otras publicaciones. Estas publicaciones más pequeñas raramente tienen fondos suficientes para pagar por adelantado, de modo que pagan conforme a un plan de cuotas.

A la mayoría de las imprentas, The Pacific les cobra USD 1000 por mes, por lo que se crea un precio reutilizable:

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

Según la marca, el modelo y la antigüedad de la imprenta, The Pacific cobra distintos importes. En este ejemplo, cobra USD 1000 por mes durante seis meses, es decir, un total de USD 6000.

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

La cantidad de iterations se multiplica por el intervalo del precio (en este ejemplo, seis pagos mensuales) para determinar la cantidad de veces que se cobra al cliente. El parámetro end_behavior qué sucede con la suscripción después de que se completa la última iteración. En un plan de cuotas, la suscripción ya no se necesita, por lo que end_behavior se establece en cancel.

En muy pocos casos, The Pacific cobra menos de USD 1000 por mes. En estas situaciones, se usa price_data para crear un precio puntual. En este ejemplo, se crea un precio de USD 500 que se cobra mensualmente durante seis 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