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

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

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 de programación de suscripciones también siguen las mismas restricciones que las suscripciones al crear fases de calendarios 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.

Calendarios de suscripciones

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

Fases

Configura la duración de una fase

Transición a la siguiente fase

Comportamiento de prorrateo

Programar el comportamiento de prorrateo de la actualización

Comportamiento de prorrateo de transición de fase

Usa las pruebas

Completa un calendario

Herencia de atributos de fases

Usa los metadatos de la fase

Crea calendarios de suscripciones

Nota

Actualiza los calendarios de suscripciones

Vista previa de una factura

Vista previa de la creación y actualizaciones del calendario

Consideraciones adicionales

Restricciones

Limitaciones del Dashboard

La suscripción se actualiza cuando se adjunta un calendario

Casos de uso

Iniciar una suscripción en el futuro

Antedatar una suscripción

Agregar un calendario a una suscripción existente

Cambiar suscripciones a un plan superior

Cambiar suscripciones a un plan inferior

Modifica suscripciones

Aumentar la cantidad

Usar cupones

Cambiar tasas impositivas

Liberar una suscripción de un calendario

Cancelar un calendario y una suscripción

Restablecer la delimitación del ciclo de facturación

Planes de cuotas