# Calendarios de suscripciones Obtén información sobre los calendarios de suscripciones y cómo usarlos. > Esta funcionalidad solo está disponible en la versión clásica del [editor de suscripciones](https://dashboard.stripe.com/subscriptions) en el Dashboard. Puedes cambiar entre la versión clásica y la nueva en cualquier momento, y tu elección persiste durante 30 días. Esto significa que cuando vuelves a abrir el editor, se establece por defecto la versión que hayas seleccionado por última vez. Usa [calendarios de suscripciones](https://docs.stripe.com/api/subscription_schedules.md) para hacer cambios automáticos a lo largo del tiempo. Puedes [crear](https://docs.stripe.com/api/subscription_schedules/create.md) suscripciones directamente a través de un calendario o puedes agregar un calendario a una suscripción existente. Usa el atributo [fases](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases) 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](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-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 Stripe Billing como en la API. Para ver ejemplos sobre cómo usar los calendarios de suscripciones, consulta los [Casos de uso](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#use-cases). ## Fases Al crear un calendario de suscripción, usa el atributo [fases](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases) 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. #### API Las fases tienen un atributo de [duración](https://docs.stripe.com/api/subscription_schedules/update.md#update_subscription_schedule-phases-duration) que puedes usar para especificar cuánto tiempo debe durar una fase. El parámetro `duration` acepta los siguientes valores: `week`, `month` o `year`. La `end_date` de una fase debe ser la `start_date` de la siguiente fase. El uso de `duration` establece la `start_date` y la `end_date` correctas de manera automática. Puedes configurar estos valores de forma manual, pero Stripe recomienda usar `duration`. 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. #### Dashboard Para establecer la duración de una fase: 1. En el Dashboard, abre el [editor de suscripciones](https://dashboard.stripe.com/subscriptions?create=subscription). 1. Agrega un nuevo cliente o encuentra uno existente. 1. Agrega un nuevo producto o encuentra uno existente. 1. Haz clic en **+ Agregar fase**. 1. Selecciona la duración de la fase. También puedes seleccionar **Para siempre** si deseas mantener la suscripción activa indefinidamente. ### 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](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-proration_behavior) 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: 1. **Programar el comportamiento de prorrateo de actualizaciones**: El parámetro de nivel superior [proration_behavior](https://docs.stripe.com/api/subscription_schedules/update.md#update_subscription_schedule-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). 1. **Comportamiento de prorrateo de transición de fase**: Cada fase tiene su propio atributo [proration_behavior](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-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](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-proration_behavior) 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. #### API Para agregar períodos de prueba, debes definir el [final del período de prueba](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-trial_end) 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. #### Dashboard Para agregar un período de prueba a la primera fase de una nueva suscripción: 1. En el Dashboard, abre el [editor de suscripciones](https://dashboard.stripe.com/subscriptions?create=subscription). 1. Agrega un nuevo cliente o encuentra uno existente. 1. Agrega un nuevo producto o encuentra uno existente. 1. En **Días de prueba gratuita**, establece la duración del período de prueba gratuito. - Si deseas que toda la fase sea un período de prueba, establece la duración de la prueba igual a la duración de la fase. - Si solo deseas que parte de la fase sea un período de prueba, establece la duración del período de prueba para que sea más corta que la duración de la fase. 1. Haz clic en **Crear suscripción**. Para agregar un período de prueba a la primera fase de una suscripción existente: 1. En el Dashboard, ve a la página [Suscripciones](https://dashboard.stripe.com/subscriptions), selecciona una suscripción existente y haz clic en **Acciones** > **Actualizar suscripción**. 1. En la suscripción, haz clic en **Editar** para la primera fase. 1. En **Días de prueba gratuita**, establece la duración del período de prueba gratuito. - Si deseas que toda la fase sea un período de prueba, establece la duración de la prueba igual a la duración de la fase. - Si solo deseas que parte de la fase sea un período de prueba, establece la duración del período de prueba para que sea más corta que la duración de la fase. 1. Haz clic en **Actualizar suscripción**. ### 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](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-end_behavior) en `cancel`. La [cancel_on_date](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-cancel_at) 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](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-default_settings-billing_thresholds) | [phases.billing_thresholds](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-billing_thresholds) | | [default_settings.collection_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-default_settings-collection_method) | [phases.collection_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-collection_method) | | [default_settings.default_payment_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-default_settings-default_payment_method) | [phases.default_payment_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-default_payment_method) | | [default_settings.invoice_settings](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-default_settings-invoice_settings) | [phases.invoice_settings](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-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. #### API Para usar metadatos de fases con la API, establece [metadatos (メタデータ)](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-metadata) 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: ```json { ... "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: ```json { ... "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: ```json { ... "object": "subscription", "metadata": { "channel": "sales", "region": "apac", "churn-risk": "high" } } ``` #### Dashboard Puedes agregar, editar y eliminar entradas de metadatos en cada fase de un calendario de suscripciones mediante el [editor de suscripciones del Dashboard de facturación](https://dashboard.stripe.com/subscriptions?create=subscription). Cuando se activa una nueva fase, los metadatos del objeto de suscripción se actualizan para que coincidan con los metadatos de esa fase. 1. En el Dashboard, abre el [editor de suscripciones](https://dashboard.stripe.com/subscriptions?create=subscription). 1. Agrega un nuevo cliente o encuentra uno existente. 1. Agrega un nuevo producto o encuentra uno existente. 1. En una fase nueva o existente, haz clic en **+ Agregar metadatos**. 1. Ingresa una **Clave** y un **Valor**, luego haz clic en **Guardar**. Obtén información sobre cómo [copiar los metadatos de las suscripciones en las facturas de suscripciones](https://docs.stripe.com/billing/invoices/subscription.md#subscription-metadata). ## Crea calendarios de suscripciones Si tu integración utiliza [Accounts configuradas por el cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), reemplaza las referencias a `Customer` y a eventos en los ejemplos de código por las referencias equivalentes de la API Accounts v2. Para obtener más información, consulta [Representar clientes con objetos Account](https://docs.stripe.com/connect/use-accounts-as-customers.md). 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. > 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](https://docs.stripe.com/billing/subscriptions/webhooks.md#understand). > > 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](https://docs.stripe.com/api/invoices/update.md). 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. #### API ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d customer=cus_GBHHxuvBvO26Ea \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]=price_1GqNdGAJVYItwOKqEHb" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=12" ``` Este calendario: - Se inicia apenas es creado. - Establece la suscripción como una instancia del producto en `price_1GqNdGAJVYItwOKqEHb`. - Dura 12 meses y luego libera la suscripción del calendario. También puedes crear calendarios de suscripciones especificando el ID de una suscripción: ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d from_subscription=sub_GB98WOvaRAWPl6 ``` 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](https://docs.stripe.com/api/subscription_schedules.md). 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](https://docs.stripe.com/api/subscription_schedules/release.md). #### Dashboard Para crear un calendario de suscripciones de varias fases: 1. En el Dashboard, abre el [editor de suscripciones](https://dashboard.stripe.com/subscriptions?create=subscription). 1. Agrega un nuevo cliente o encuentra uno existente. 1. Agrega un nuevo producto o encuentra uno existente. 1. Establece una duración para la primera fase del calendario de suscripciones. 1. Haz clic en **+ Agregar fase**. 1. Selecciona la duración de la fase. También puedes seleccionar **Para siempre** si deseas mantener la suscripción activa indefinidamente. 1. Realiza los cambios necesarios en la nueva fase. Puedes cambiar la cantidad, modificar el precio, agregar o eliminar cupones, restablecer la fecha del período 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. 1. Guarda la nueva fase. 1. Agrega las fases adicionales según sea necesario. 1. Haz clic en **Programar suscripción**. ## Actualiza los calendarios de suscripciones En los calendarios de suscripciones, solo puedes actualizar las fases actuales y futuras. #### API 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 actualiza la `quantity` a dos: ```curl curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}} \ -u "<>:" \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=2" \ -d "phases[0][start_date]=1577865600" \ -d "phases[0][end_date]=1580544000" ``` 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: ```curl curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}} \ -u "<>:" \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][start_date]=1577865600" \ -d "phases[0][end_date]=now" \ -d "phases[1][items][0][price]={{PRICE_ID}}" \ -d "phases[1][items][0][quantity]=2" \ -d "phases[1][start_date]=now" \ -d "phases[1][end_date]=1580544000" ``` Para agregar fases adicionales a un calendario de suscripción, especifica la fase actual y luego define las nuevas fases: ```curl curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}} \ -u "<>:" \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][start_date]=1577865600" \ -d "phases[0][end_date]=1580544000" \ -d "phases[1][items][0][price]={{PRICE_ID}}" \ -d "phases[1][items][0][quantity]=2" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=1" ``` #### Dashboard Para actualizar las suscripciones existentes, de modo que cuenten con futuras fases de calendarios de suscripciones, 1. En el Dashboard, ve a la página [Suscripciones](https://dashboard.stripe.com/subscriptions), selecciona una suscripción existente y haz clic en **Acciones** > **Actualizar suscripción**. 1. Establece una duración para la fase actual del calendario de suscripciones seleccionando una fecha de finalización. 1. Haz clic en **+Agregar fase**. 1. selecciona la duración de tu próxima fase. También puedes seleccionar **Para siempre** si deseas mantener la suscripción activa indefinidamente. 1. Realiza los cambios necesarios en la nueva fase. Puedes cambiar la cantidad, modificar el precio, agregar o eliminar cupones, restablecer la fecha del período 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. 1. Guarda la nueva fase. 1. Agrega las fases adicionales según sea necesario. 1. Haz clic en **Programar suscripción**. ## Vista previa de una factura Usa el parámetro [calendario](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule) en [create preview](https://docs.stripe.com/api/invoices/create_preview.md) para obtener una vista previa de la próxima factura de un calendario de suscripción. ```curl curl https://api.stripe.com/v1/invoices/create_preview \ -u "<>:" \ -d "schedule={{SUBSCRIPTIONSCHEDULE_ID}}" ``` ### Vista previa de la creación y actualizaciones del calendario Usa los parámetros en [schedule_details](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule_details) para obtener una vista previa de cómo crear o actualizar un calendario de suscripción. Especifica un [calendario](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule) existente para decirle a Stripe si se trata de una creación o una actualización. Especifica todas las [fases](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule_details-phases) 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. ```curl curl https://api.stripe.com/v1/invoices/create_preview \ -u "<>:" \ -d "customer_details[address][line1]=920 5th Ave" \ -d "customer_details[address][city]=Seattle" \ -d "customer_details[address][state]=WA" \ -d "customer_details[address][postal_code]=98104" \ -d "customer_details[address][country]=US" \ -d "schedule_details[phases][0][start_date]=now" \ -d "schedule_details[phases][0][items][0][price]={{PRICE_ID}}" \ -d "schedule_details[phases][0][items][0][quantity]=1" \ -d "schedule_details[phases][0][duration][interval]=month" \ -d "schedule_details[phases][0][duration][interval_count]=12" ``` ## 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](https://docs.stripe.com/billing/subscriptions/quantities.md#billing-periods-with-multiple-prices) 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](https://dashboard.stripe.com/test/subscriptions). 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](https://docs.stripe.com/api/subscription_schedules.md) 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](https://docs.stripe.com/api/subscription_schedules.md) para modificar la suscripción, en lugar de la API [Subscriptions](https://docs.stripe.com/api/subscriptions.md#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](https://docs.stripe.com/api/subscription_schedules/create.md) o a través del webhook [subscription_schedule.created](https://docs.stripe.com/api/events/types.md#event_types-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](https://docs.stripe.com/customer-management/configure-portal.md#configure-subscription-management). - 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](https://docs.stripe.com/api/subscription_schedules/release.md) o a través del evento de webhook [subscription_schedule.released](https://docs.stripe.com/api/events/types.md#event_types-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](https://docs.stripe.com/api/subscription_items/delete.md) uno de los ítems, esto divide automáticamente la fase del calendario de suscripciones adjunto en dos fases: 1. La fase que acaba de terminar y tenía dos ítems de suscripción 1. 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`](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-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` | ✓ Supported | - Unsupported | | `trial_end` | ✓ Supported | - Unsupported | | `tax_rates` | ✓ Supported | - Unsupported | | `application_fee_percent` | ✓ Supported | ✓ Supported | | `discounts` | ✓ Supported | - Unsupported | | `collection_method` | ✓ Supported | ✓ Supported | | `invoice_settings` | ✓ Supported | ✓ Supported | | `default_payment_method` | ✓ Supported | ✓ Supported | | `default_source` | ✓ Supported | ✓ Supported | | `transfer_data` | ✓ Supported | ✓ Supported | | `on_behalf_of` | ✓ Supported | ✓ Supported | | `currency` | ✓ Supported | - Unsupported | | `add_invoice_items` | ✓ Supported | - Unsupported | | `automatic_tax` | ✓ Supported | ✓ Supported | | `items.prices` | ✓ Supported | - Unsupported | | `billing_thresholds` | ✓ Supported | ✓ Supported | 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: ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -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][duration][interval]=month" \ -d "phases[0][duration][interval_count]=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. Antedatar te permite cobrar por tiempo en el pasado y les permite a los suscriptores digitales acceder al sitio web de inmediato. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -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][duration][interval]=month" \ -d "phases[0][duration][interval_count]=12" ``` ### 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. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "from_subscription={{SUBSCRIPTION_ID}}" ``` 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](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#upgrading-subscriptions) 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. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -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][duration][interval]=month" \ -d "phases[0][duration][interval_count]=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][duration][interval]=month" \ -d "phases[1][duration][interval_count]=11" ``` ### 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* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) utilizan esta opción para probar ambas publicaciones y ver cuál les gusta más. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -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][duration][interval]=month" \ -d "phases[0][duration][interval_count]=1" \ -d "phases[1][items][0][price]={{PRICE_PRINT}}" \ -d "phases[1][items][0][quantity]=1" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=11" ``` ### 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. #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') # Create a subscription schedule with the existing subscription schedule = client.v1.subscription_schedules.create({ from_subscription: 'sub_ERf72J8Sc7qx7D', }) # Update the schedule with the new phase client.v1.subscription_schedules.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, }, ], duration: { interval: 'month', interval_count: 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 curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -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][duration][interval]=month" \ -d "phases[0][duration][interval_count]=1" \ -d "phases[1][items][0][price]={{PRICE_ID}}" \ -d "phases[1][items][0][quantity]=2" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=11" ``` ### 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. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -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][duration][interval]=month" \ -d "phases[0][duration][interval_count]=6" \ -d "phases[0][discounts][0][coupon]={{COUPON_ID}}" \ -d "phases[1][items][0][price]={{PRICE_ID}}" \ -d "phases[1][items][0][quantity]=1" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=6" ``` ### 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. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -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][duration][interval]=month" \ -d "phases[0][duration][interval_count]=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][duration][interval]=month" \ -d "phases[1][duration][interval_count]=11" ``` ### Liberar una suscripción de un calendario Puedes [liberar](https://docs.stripe.com/api/subscription_schedules/release.md) 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. ```curl curl -X POST https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}}/release \ -u "<>:" ``` ### 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`. ```curl curl -X POST https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}}/cancel \ -u "<>:" ``` ### 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. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -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][duration][interval]=month" \ -d "phases[1][duration][interval_count]=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 curl https://api.stripe.com/v1/prices \ -u "<>:" \ -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. #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_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" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -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: #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_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" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -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" ```