Calendarios de suscripciones
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 phases para definir los cambios que quieres 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
El resto de este documento 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 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 de 50 % descuento durante los primeros tres meses de una suscripción. En este escenario, debes crear un calendario de suscripción cuya primera fase dura tres meses, con un cupón de 50 % de descuento. En la segunda fase, la suscripción recupera el costo normal y el cupón se elimina. Las fases deben ser secuenciales, es decir, que solo una fase puede ser activada en un determinado momento.
Configura la duración de una fase
El intervalo de un precio determina con qué frecuencia se factura una suscripción. Por ejemplo, si el intervalo es mensual, se factura 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
Puedes agregar períodos de prueba definiendo 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 la finalización de 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 la finalización de 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:
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.
Aprende a 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 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 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.
This means that, for example, creating a charge-automatically subscription schedule with start_date=now
also creates a subscription and an invoice in the draft
status. This gives you a 1-hour window to make edits to the invoice. Later, the invoice is auto-advanced into the open
or paid
status depending on the outcome of the asynchronous payment attempt at finalization time.
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.
Crear calendarios de suscripciones sin código
Puedes crear calendarios de suscripción de varias fases sin usar código en el editor de suscripciones de Stripe Billing. Para hacerlo, sigue estos pasos:
- En el Dashboard, abre el editor de suscripciones.
- Agrega a un cliente.
- Agrega un precio al menú desplegable de selección de productos.
- Establece una duración para la primera fase del calendario de suscripciones.
- Haz clic en + Agregar fase.
- Selecciona la duración de la próxima fase, o selecciona para siempre para mantener la suscripción activa.
- Realiza los cambios necesarios en la nueva fase. Puedes cambiar la cantidad, modificar el precio, agregar o eliminar cupones, restablecer la fecha del ciclo de facturación, cambiar el comportamiento del prorrateo o actualizar los metadatos. Si cambias los metadatos en una fase, se actualizan los metadatos de la suscripción cuando se activa esa fase.
- Guarda la nueva fase.
- Agrega las fases adicionales según sea necesario.
- Crea una suscripción.
Actualiza los calendarios de suscripciones
En los calendarios de suscripciones, solo puedes actualizar fases actuales y futuras. Al actualizar un calendario de suscripción, debes especificar todas las fases actuales y futuras. También debe pasar cualquier parámetro previamente establecido que desee mantener. Los parámetros que se establecieron anteriormente no se establecen para la fase existente, a menos que los pases en la solicitud de actualización. En la respuesta, sigues 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:
Actualiza los calendarios de suscripciones sin código
Puedes actualizar las suscripciones existentes para tener fases futuras de calendario de suscripciones con el editor de suscripciones de Stripe Billing. Para hacerlo, sigue estos pasos:
- En el Dashboard, ve a la página Suscripciones, selecciona una suscripción existente y haz clic en Acciones > Actualizar suscripción.
- Establece una duración para la fase actual del calendario de suscripciones seleccionando una fecha de finalización.
- Haz clic en +Agregar fase.
- Selecciona la duración de la próxima fase, o selecciona para siempre para mantener la suscripción activa.
- Realiza los cambios necesarios en la nueva fase. Puedes cambiar la cantidad, modificar el precio, agregar o eliminar cupones, restablecer la fecha del ciclo de facturación, cambiar el comportamiento del prorrateo o actualizar los metadatos. Si cambias los metadatos en una fase, se actualizan los metadatos de la suscripción cuando se activa esa fase.
- Guarda la nueva fase.
- Agrega las fases adicionales según sea necesario.
- Crea una suscripción.
Vista previa de una factura
Usa el parámetro de calendario en la API de la próxima factura para acceder a una vista previa de la próxima factura de un calendario de suscripciones.
Vista previa de la creación y actualizaciones del calendario
Usa los parámetros de schedule_details para acceder a una vista previa de la creación o la actualización de un calendario de suscripciones. Establece un calendario existente para indicarle a Stripe si se trata de una creación o de una actualización.
Aprueba todas las actuales y futuras fases que vas a previsualizar.
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.
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