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. A continuación, puede ver un breve video sobre cómo funcionan los calendarios de suscripciones en el Dashboard:

Calendarios de suscripciones en el Dashboard

En el resto de este documento, se da más detalles sobre los calendarios de suscripciones. Para ver una lista de ejemplos, consulta la página casos de uso.

Fases

Al crear un calendario de suscripciones, usa el atributo fases para definir cuándo se producirán los cambios y qué propiedades de la suscripción deberás modificar. Por ejemplo, podrías ofrecer un cupón de 50 % descuento durante los primeros tres meses de una suscripción. En este caso, deberías crear un calendario de suscripción cuya primera fase durara tres meses y tuviera un cupón de 50 % de descuento. En la segunda fase, la suscripción recuperaría el costo normal y el cupón se eliminaría. Las fases deben ser secuenciales, es decir, que solo una fase puede estar activa en un determinado momento. 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

La transición de una fase a otra se hace automáticamente al alcanzar 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, activar el prorrateo para acreditarle al usuario el tiempo o los ítems no utilizados del plan.

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. No se elimina la suscripción, pero ya no estará asociada al calendario. Si quieres cancelar una suscripción después de que se completa la última fase del calendario, puedes establecer end_behavior en cancel.

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.
Metadata from the phase with non-empty values are used to update the metadata on the subscription if the keys are already present in the latter.
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": ""
      },
    }
  ],
}

When this schedule creates a new subscription and the subscription enters Phase 1, the three keys in Phase 1 metadata are added to the subscription’s metadata. Hence, the subscription in Phase 1 has the following metadata:

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

The value of channel is updated because a value is specified on the phase’s metadata and the subscription already has metadata with that key.
The value of region is unchanged because it’s not specified on the phase.
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.

Hence, the subscription in Phase 2 has the following metadata:

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

Encontrarás ejemplos más completos en la página de casos de uso, pero a continuación se da un ejemplo básico de cómo crear un calendario de suscripción usando un cliente. Si se crea un calendario de esta manera, también se creará 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 el que se crea la suscripción del calendario. El estado inicial de la factura es draft y Stripe la finaliza alrededor de una hora después de su creación.

Esto significa que, por ejemplo, al crear un calendario de suscripciones con cobros automáticos usando start_date=now, también se crean una suscripción y una factura en estado draft. Tienes una hora para modificar la factura. Luego, la factura pasa a tener el 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`	X
`trial_end`	X
`tax_rates`	X
`application_fee_percent`	X	X
`discounts`	X
`collection_method`	X	X
`invoice_settings`	X	X
`default_payment_method`	X	X
`default_source`	X	X
`transfer_data`	X	X
`on_behalf_of`	X	X
`billing_thresholds`	X	X
`currency`	X
`add_invoice_items`	X
`automatic_tax`	X	X
`items.prices`	X

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

Consulta también

Casos de uso de calendarios de suscripciones