Calendarios de suscripciones

Obtén información sobre los calendarios de suscripciones y cómo usarlos.

Usa calendarios de suscripciones para hacer cambios automáticos a lo largo del tiempo. Puedes crear suscripciones directamente a través de un calendario o puedes agregar un calendario a una suscripción existente. Usa el atributo fases para definir los cambios que quieras hacer a la suscripción. Una vez que el calendario completa todas las fases, finaliza conforme a su end_behavior.

Estos son algunos de los cambios que puedes querer programar:

Iniciar una suscripción en una fecha futura
Antedatar una suscripción a una fecha pasada
Cambiar la categoría del plan de suscripción

Los calendarios de suscripciones están disponibles tanto en el Dashboard de Stripe Billing como en la API. Este video muestra cómo funcionan los calendarios de suscripciones en el Dashboard:

Calendarios de suscripciones en el Dashboard

Para ver ejemplos sobre cómo usar los calendarios de suscripciones, consulta los Casos de uso.

Fases

Al crear un calendario de suscripción, usa el atributo fases para definir cuándo se producirán los cambios y qué propiedades de suscripción modificar. Por ejemplo, puedes ofrecer un cupón del 50 % de descuento durante los primeros tres meses de una suscripción. En este escenario, deberías crear un calendario de suscripción cuya primera fase dure tres meses, con un cupón de descuento del 50 %. En la segunda fase, la suscripción vuelve al costo normal y se elimina el cupón. Las fases deben ser secuenciales, lo que significa que solo una fase puede estar activa en un momento dado. Puedes tener hasta 10 fases.

Configura la duración de una fase

Puedes establecer la duración de una fase mediante el uso de la API o el Dashboard.

El intervalo de un precio determina con qué frecuencia se cobra una suscripción. Por ejemplo, si el intervalo es mensual, se cobra todos los meses. Las fases tienen un atributo iteraciones que usas para especificar cuánto debe durar cada fase. Multiplica este valor por el intervalo para determinar la duración de la fase. Si un calendario de suscripción usa un precio con un intervalo mensual y estableces iterations=2, la fase dura dos meses.

La end_date de una fase debe ser la start_date de la siguiente fase. El uso de iterations establece la start_date y la end_date correctas en forma automática. Puedes configurar estos valores manualmente, pero Stripe recomienda usar iterations. Como la configuración manual de las fechas de inicio y finalización puede dar lugar a errores, úsala solamente para casos de uso avanzados.

Transición a la siguiente fase

Las transiciones de fase se producen automáticamente cuando se alcanza la end_date de una fase. Cuando comienza una fase, Stripe actualiza la suscripción basándose en los atributos de la siguiente fase. Puedes, como alternativa, habilitar prorrateos para acreditar al usuario por el tiempo o los ítems no utilizados en el plan.

Comportamiento de prorrateo

Existen dos configuraciones diferentes del comportamiento de prorrateo que controlan la forma en que Stripe gestiona los ajustes de facturación durante los cambios en el calendario de suscripciones:

Programar el comportamiento de prorrateo de actualizaciones: El parámetro de nivel superior proration_behavior controla cómo gestionar los prorrateos cuando se actualiza un calendario de suscripción de forma que afecte a la configuración de facturación de la fase actual (por ejemplo, al cambio de precios o cantidades).
Comportamiento de prorrateo de transición de fase: Cada fase tiene su propio atributo proration_behavior que controla cómo Stripe gestiona los prorrateos al pasar a esa fase.

Programar el comportamiento de prorrateo de la actualización

Cuando actualizas un calendario de suscripciones y cambias la configuración de facturación de current_phase, puedes controlar cómo se gestionan los prorrateos usando el parámetro proration_behavior de nivel superior.

Este parámetro funciona de manera similar al de Actualizar una API de suscripción y acepta los siguientes valores:

(predeterminado) create_prorations: Genera ajustes de prorrateo para los cambios en la facturación.
none: No se crean prorrateos para la actualización.
always_invoice: Genera prorrateos y finaliza la factura de inmediato.

Los cambios en campos que no son de facturación (como los metadatos) no generarán prorrateos independientemente de esta configuración.

Comportamiento de prorrateo de transición de fase

Cada fase puede definir su propio proration_behavior para controlar lo que sucede cuando la suscripción entra en esa fase. Esta configuración se aplica específicamente a los prorrateos generados durante las transiciones de fase y se guarda como un campo en la fase.

Por ejemplo, si phases[1] aumenta la cantidad de 1 a 3 cuando comienza, el proration_behavior de phases[1] determina cómo se gestionarán esos prorrateos al pasar de phases[0] a phases[1]:

(predeterminado) create_prorations: Genera ítems de factura pendientes para cambios en la facturación.
none: Al entrar en esta fase, no se crean prorrateos.
always_invoice: Genera prorrateos y crea inmediatamente una factura al entrar en esta fase.

Si necesitas cambiar la manera en que una transición de fase futura gestiona los prorrateos, actualiza la configuración proration_behavior en la fase futura antes de que se active.

Usa las pruebas

Puedes agregar un período de prueba a la primera fase de una suscripción mediante el uso de la API o el Dashboard.

Para agregar períodos de prueba, debes definir el final del período de prueba en una fase. Si quieres que la fase completa sea un período de prueba, establece el mismo valor para trial_end y para el parámetro end_date de la fase. Si quieres que el período de prueba solo dure parte de la fase, también puedes establecer la fecha trial_end un poco antes de end_date. Al programar actualizaciones, debes especificar el nuevo parámetro trial_end de cada fase.

Completa un calendario

Los calendarios de suscripciones finalizan después de que se completa la última fase. En este punto, la suscripción se mantiene y ya no está asociada al calendario. Si quieres cancelar una suscripción después de que se completa la última fase de un calendario, puedes establecer end_behavior en cancel. La cancel_on_date de la suscripción no se define hasta que la suscripción pasa a la fase final.

Herencia de atributos de fases

Cuando se activa una fase, todos los atributos definidos en la fase también se establecen en la suscripción. Después de la finalización de la fase, los atributos siguen siendo los mismos a menos que se los modifique en la siguiente fase o el calendario no tenga una configuración predeterminada. Puedes definir algunos atributos tanto en los calendarios como en las fases. Por ejemplo:

Atributo de calendario	Atributo de fase
default_settings.billing_thresholds	phases.billing_thresholds
default_settings.collection_method	phases.collection_method
default_settings.default_payment_method	phases.default_payment_method
default_settings.invoice_settings	phases.invoice_settings

Si uno de estos atributos se define en el calendario, se convierte en el valor predeterminado para todas las fases. Cuando la misma propiedad se define tanto en el calendario como en la fase, el atributo de la fase anula el atributo del calendario. Este comportamiento se explica mejor a continuación:

Atributo de calendario presente	Atributo de fase presente	Resultado
No	No	Se establece de manera predeterminada en la configuración del cliente o de la cuenta
Sí	No	Atributo de calendario definido
Sí	Sí	Atributo de fase definido
No	Sí	Atributo de fase definido

Usa los metadatos de la fase

Puedes usar las fases de programación de suscripción para establecer metadatos en la suscripción subyacente. Esto te permite controlar los metadatos de una suscripción con actualizaciones programadas.

Para usar metadatos de fases con la API, establece metadatos (メタデータ) en las fases de un calendario de suscripciones. Cuando la suscripción subyacente ingresa a una fase, sucederá lo siguiente:

Los metadatos de la fase con valores no vacíos se agregan a los metadatos de la suscripción si las claves no están ya presentes en esta última.
Los metadatos de la fase con valores no vacíos se usan para actualizar los metadatos de la suscripción si las claves ya están presentes en esta última.
Los metadatos de la fase con valores vacíos se usan para quitar las claves correspondientes en los metadatos de la suscripción.

Para quitar todas las claves de los metadatos de la suscripción, actualízala directamente o quita todas las claves de forma manual desde los metadatos de la fase. Actualizar directamente los metadatos de la suscripción subyacente no afecta los metadatos de la fase actual.

El siguiente ejemplo muestra un calendario de suscripción con dos fases, cada una con sus propios metadatos:

{
  ...
  "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": ""
      },
    }
  ],
}

Cuando este calendario crea una suscripción nueva y esta entra en Phase 1, las tres claves de los metadatos de la Phase 1 se agregan a los metadatos de la suscripción. Por lo tanto, la suscripción en Phase 1 contiene los siguientes metadatos:

{
  ...
  "object": "subscription",
  "metadata": {
    "channel": "self-serve",
    "region": "apac",
    "upsell-products": "alpha"
  },
}

Cuando la suscripción entra en Phase 2, se actualizan los metadatos de la suscripción:

El valor de channel se actualiza porque se especifica un valor en los metadatos de la fase y la suscripción ya contiene metadatos con esa clave.
El valor de region no se modifica porque no está especificado en la fase.
churn-risk se agrega porque esta es una clave nueva.
upsell-products no está definido porque hay un valor vacío especificado en la fase.

Por lo tanto, la suscripción en Phase 2 contiene los siguientes metadatos:

{
  ...
  "object": "subscription",
  "metadata": {
    "channel": "sales",
    "region": "apac",
    "churn-risk": "high"
  }
}

Obtén información sobre cómo copiar los metadatos de las suscripciones en las facturas de suscripciones.

Crea calendarios de suscripciones

Este ejemplo muestra cómo crear un calendario de suscripciones usando un cliente. Si se crea un calendario de esta manera, también se crea la suscripción.

Nota

A diferencia de cuando se crea una suscripción directamente, la primera factura de un calendario de suscripciones con collection_method establecido en charge_automatically se comporta como si fuera una factura recurrente y no se finaliza de inmediato en el momento en que se crea la suscripción del calendario. El estado inicial de la factura es draft y Stripe la finaliza aproximadamente una hora después de su creación.

Por ejemplo, al crear un calendario de suscripciones con el método de cobro configurado para cobro automático y con start_date=now, también se crean una suscripción y una factura en estado draft. Tienes 1 hora para editar la factura. Luego, la factura pasa automáticamente al estado open o paid, según el resultado del intento asincrónico de pago en el momento de la finalización.

Este calendario:

Se inicia apenas es creado.
Establece la suscripción como una instancia del producto en price_1GqNdGAJVYItwOKqEHb.
Pasa por 12 iteraciones y luego libera la suscripción del calendario.

También puedes crear calendarios de suscripciones especificando el ID de una suscripción:

Si se crea un calendario de esta manera, se usan atributos de la suscripción para definir atributos del calendario.

Al igual que con otras API de Stripe, puedes recuperar y actualizar los calendarios de suscripciones. También puedes cancelarlos y liberarlos. Cuando se cancela un calendario de suscripción, también se cancela la suscripción. Si solo quieres eliminar el calendario de una suscripción, usa la llamada para liberarlo.

Actualiza los calendarios de suscripciones

En los calendarios de suscripciones, solo puedes actualizar las fases actuales y futuras.

Al actualizar un calendario de suscripción, debes especificar todas las fases actuales y futuras. También debes especificar los parámetros previamente establecidos que desees mantener. Los parámetros que se establecieron anteriormente no se establecerán para la fase existente, a menos que los especifiques en la solicitud de actualización. En la respuesta, seguirás recibiendo información sobre fases anteriores.

Puedes incluir hasta 10 fases actuales o futuras. La actualización de la fase activa también actualiza la suscripción subyacente. Por ejemplo, esta llamada mantiene las fechas de inicio y finalización existentes, pero modifica la quantity a dos:

También puedes finalizar la fase actual de inmediato e iniciar una nueva fase. Esto moverá la fase activa al pasado y aplicará enseguida la nueva fase a la suscripción. En el siguiente ejemplo, cuando finaliza la fase actual, se inicia una nueva fase:

Para agregar fases adicionales a un calendario de suscripción, especifica la fase actual y luego define las nuevas fases:

Vista previa de una factura

Usa el parámetro calendario en create preview para obtener una vista previa de la próxima factura de un calendario de suscripción.

Vista previa de la creación y actualizaciones del calendario

Usa los parámetros en schedule_details para obtener una vista previa de cómo crear o actualizar un calendario de suscripción. Especifica un calendario existente para decirle a Stripe si se trata de una creación o una actualización.

Especifica todas las fases actuales y futuras para las que accederás a una vista previa.

Por ejemplo, el siguiente código muestra una vista previa de la primera factura de un calendario de suscripciones con la fase 1’ que dura 12 períodos de facturación.

Consideraciones adicionales

Los calendarios de suscripciones generalmente siguen las mismas restricciones que las suscripciones, pero también incoporan algunas propias. Además, la interacción entre los calendarios de suscripciones y las suscripciones puede producir un comportamiento inesperado. Revisa las siguientes secciones para comprender las limitaciones, el comportamiento del producto y las prácticas recomendadas generales al usar los calendarios de suscripciones.

Restricciones

Solo puedes definir hasta 10 fases actuales o futuras a la vez en un calendario de suscripciones. Las fases pasadas no se contabilizan para este límite.
Las fases del calendario de suscripciones también tienen las mismas restricciones que las suscripciones cuando se crean las fases del calendario de suscripciones con varios ítems.

Limitaciones del Dashboard

Puedes crear y actualizar calendarios de suscripciones sin código en el Dashboard.

En el Dashboard, puedes establecer los siguientes ajustes de forma global en todas las fases, pero no por fases:

Umbrales de facturación
Métodos de pago
Configuración de factura
Descripción de la suscripción
Días de prueba (solo funciona con la primera fase)

Los siguientes parámetros no son compatibles con el Dashboard:

Metadatos del programa de suscripciones
Metadatos del ítem de fase
Moneda
Todos los parámetros de Connect

La suscripción se actualiza cuando se adjunta un calendario

Usa los calendarios de suscripciones para modificar las suscripciones automáticamente cuando pase el tiempo y se ingrese la siguiente fase del calendario. Algunos cambios que realizas directamente en la suscripción se propagan a las fases del calendario de suscripciones, pero otros no. Esto significa que el calendario de suscripciones podría reescribir cualquier modificación que realices directamente en la suscripción cuando se ingrese a la siguiente fase.

Cuando programes cambios en una suscripción, sigue estas prácticas recomendadas:

Si una suscripción tiene un calendario de suscripciones adjunto, usa la API Subscription Schedule para modificar la suscripción, en lugar de la API Subscriptions.
Almacena las ID del calendario de suscripciones junto con la ID de la suscripción para futuras actualizaciones de la API. La ID del calendario de suscripciones se devuelve cuando usas la API para crearla o a través del webhook subscription_schedule.created cuando Stripe la crea en forma automática, como cuando un cliente programa un cambio a un plan inferior en el Portal del cliente.
Descarta las ID del calendario de suscripciones cuando se publique un calendario de suscripciones. Puedes realizar cambios en las suscripciones directamente o crear un nuevo calendario de suscripciones. El ID del calendario se devuelve cuando se publica con la API o a través del evento de webhook subscription_schedule.released cuando se publica el calendario de suscripción.
De ser posible, usa el Dashboard para modificar las suscripciones, lo que actualiza automáticamente cualquier calendario de suscripción adjunto.

Específicamente, cuando cambias cualquiera de los siguientes atributos de suscripción directamente en una suscripción, esta acción podría crear automáticamente una nueva fase de calendario de suscripciones:

discounts
tax_rates
items
trial_end, trial_settings, trial_start
application_fee_percent
add_invoice_items
automatic_tax

Por ejemplo, considera una suscripción con dos ítems. La suscripción tiene un calendario de suscripciones adjunto con una sola fase, que refleja el estado actual de la suscripción. Si usas la API para eliminar uno de los ítems, esto divide automáticamente la fase del calendario de suscripciones adjunto en dos fases:

La fase que acaba de terminar y tenía dos ítems de suscripción
La nueva fase que tiene solo un elemento en la suscripción

Cuando las fases del cronograma de suscripción se dividen automáticamente, las siguientes propiedades se copian de la fase actual a la nueva fase:

proration_behavior
billing_cycle_anchor
cancel_at_period_end
description
metadata
pause_collection

Además, Stripe podría copiar los siguientes atributos de suscripción de nivel superior en el calendario de suscripciones o en sus default_settings:

Atributo de suscripción	Se ha copiado a la nueva fase de calendario de suscripciones	Copiado en el calendario de suscripciones `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`

Las actualizaciones de metadata de suscripción no se propagan a un calendario de suscripciones adjunto.

Casos de uso

Para entender los calendarios de suscripciones, imaginemos la empresa de un diario ficticio llamado The Pacific que 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

De forma predeterminada, las nuevas suscripciones a la versión impresa comienzan el primer día del mes siguiente. Para ello, establece la start_date en un punto en el futuro. En el siguiente código, se crea una suscripción que comienza en el futuro:

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. Antedatar te permite cobrar por tiempo en el pasado y les permite a los suscriptores digitales acceder al sitio web de inmediato.

Agregar un calendario a una suscripción existente

The Pacific podría descubrir que algunos de sus clientes originales tienen suscripciones sin calendarios. Dado que estas suscripciones ya existen, puedes especificar las ID de las suscripciones en el atributo from_subscription para agregar un calendario. La especificación de las ID de suscripción de esta manera crea un calendario con una fase basada en el período de facturación actual de la suscripción.

Mientras se agregan estos calendarios, algunos clientes deciden obtener una suscripción a la versión impresa, por lo 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 caso de uso Actualizar suscripciones 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 primero la publicación impresa y luego decidir si quieren continuar con la suscripción o cancelarla.

Cambiar suscripciones a un plan inferior

The Pacific también ofrece una opción para comenzar con una suscripción a ambas publicaciones, la impresa y la digital, y luego bajar de plan para recibir solo la versión impresa por el resto de la suscripción. Los clientes utilizan esta opción para probar ambas publicaciones y ver cuál les gusta más.

Modifica suscripciones

The Pacific ofrece dos opciones de suscripción impresa: una opción básica con anuncios o una opción prima sin anuncios. Algunos clientes que eligen la opción prima quieren cambiar a la opción básica en el próximo período de facturación. Puedes crear un cronograma utilizando la suscripción existente y, luego, actualizarlo con la opción básica con anuncios como una nueva fase.

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.

Usar cupones

The Pacific ocasionalmente ofrece suscripciones especiales. El siguiente calendario comienza con la publicación impresa del cliente con un 50 % de descuento durante seis meses. El calendario elimina el cupón de la suscripción en la segunda fase por los seis meses restantes.

Cambiar tasas impositivas

The Pacific opera en varias jurisdicciones, y algunas tienen tasas impositivas exclusivas para las empresas basadas en 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.

Liberar una suscripción de un calendario

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

Cancelar un calendario y una suscripción

Si un calendario de suscripciones tiene una suscripción activa, puedes cancelarlo de inmediato, junto con la suscripción asociada. Solo puedes cancelar un calendario de suscripciones si su estado es not_started o active.

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

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:

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.

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: