Cambiar el plan de una suscripción
Mueve una suscripción a un plan, con efecto en su próxima renovación.
Dos comportamientos, un endpoint
El comportamiento que obtienes depende de si la suscripción ya está en un plan.CANCELED con un
cancellation_source de PLAN_CHANGE, y la suscripción de reemplazo hereda los ciclos de facturación
restantes de la original y su fecha de próxima renovación: availability.start_at y
billing_cycles.next_at en la de reemplazo son iguales al next_at de la original, y su
billing_cycles.current se reinicia en 1. Si esa fecha de renovación ya pasó (por
ejemplo, en una suscripción pausada durante mucho tiempo), la de reemplazo comienza en
aproximadamente un minuto y factura de inmediato.
end_reason CANCELED y no se traslada al reemplazo. El reemplazo recibe la promoción AUTOMATIC del nuevo plan, si el plan tiene una. Una suscripción que no está en un plan se asocia en el lugar, como en la tabla anterior: no se reemplaza ni se cancela nada, y no se agrega ninguna promoción automática. Para conservar la promoción actual de una suscripción que ya está en un plan, usa en su lugar un cambio de plan con promotion_behavior establecido en KEEP. Consulta Update Subscription y Promociones en planes de suscripción.Webhooks
Un cambio de plan a plan emite tres eventos:subscription.createpara la suscripción de reemplazo.subscription.cancelpara la original, concancellation_source: PLAN_CHANGE. No lo cuentes como cancelación de clientes (churn).subscription.plan_changedpara la suscripción de reemplazo, conprevious_subscription_iddefinido.
TRIALING en esta llamada.
Omitir el periodo de prueba del plan de destino
Si el plan de destino define fases de prueba o de introducción, la suscripción adopta toda esa secuencia por defecto, lo que significa que un suscriptor puede cambiar de plan durante una prueba y recibir una prueba nueva. Estableceskip_trial en true para evitarlo. La suscripción de reemplazo factura el precio regular del plan de destino
desde su primer cobro y su estado se mantiene ACTIVE en lugar de pasar a TRIALING.
skip_trial tiene como valor predeterminado false y se aplica solo a los cambios de plan a plan. Enviar
skip_trial: true en una suscripción que no está en un plan devuelve 400; false y una
omisión del indicador son equivalentes y se aceptan en todos los casos. En un plan sin fases no
hace ninguna diferencia.
phases sigue describiendo el planCon skip_trial: true, la respuesta sigue listando las phases del plan de destino: ese arreglo
describe el plan, no lo que se facturará a esta suscripción. Las señales a nivel de suscripción
son status, que se mantiene ACTIVE en lugar de pasar a TRIALING, y la ausencia
de current_phase y billing_phases: ambas claves se omiten de la respuesta en lugar de
devolverse como null, así que verifica la ausencia, no null. Un cambio predeterminado devuelve ambas
con valores.Conservar el mismo id
El objeto plan_change de Actualizar suscripción
cambia el plan de una suscripción en el mismo registro: el id nunca cambia, no se cancela nada
y no se dispara el webhook subscription.cancel. Ninguno de los dos mecanismos cobra en el momento, y tampoco
se prorratea ni se reembolsa nada en ningún caso. Se diferencian en lo que ocurre con el registro de la suscripción:
id,
usa plan_change con effective: IMMEDIATE en lugar de este endpoint.
plan_change no es un sustituto general: requiere una suscripción que ya esté en un
plan y que esté ACTIVE o TRIALING. Asociar un plan a una suscripción que no tiene ninguno, o
cambiar de plan desde CREATED o PAUSED, solo es posible mediante este endpoint.
Los dos se diferencian en su comportamiento predeterminado respecto a la prueba, por motivos de retrocompatibilidad:
skip_trial o phases_behavior de forma explícita siempre que el comportamiento de la prueba sea importante para ti.
Llamadas repetidas
Mientras la suscripción esté en un estado aceptado, volver a enviar su plan actual es una operación idempotente sin efecto que devuelve200 con la suscripción sin cambios, incluso si
solo cambias skip_trial, e incluso si ese plan se canceló después.
Un cambio de plan a plan no se puede repetir sobre el mismo subscription_id. Una vez que tiene éxito, la
original queda CANCELED, por lo que volver a enviar a ese id devuelve 400 INVALID_STATE
(The subscription status CANCELED does not support plan changes.) en lugar de repetir el
primer resultado. Trata ese error como confirmación de que el cambio ya se realizó, y dirige cualquier
llamada posterior al id de la suscripción de reemplazo.
Si una llamada excede el tiempo de espera, concilia con GET /v1/subscriptions/{subscription_id} en lugar de
reintentar a ciegas: la original lleva cancellation_source: PLAN_CHANGE una vez que el cambio
se realizó, y la de reemplazo es la suscripción cuyo previous_subscription_id es ese
id. Un reintento en curso enviado mientras la original aún se puede cambiar es seguro: se
deduplica siempre que skip_trial no cambie. Un valor distinto de skip_trial es una
operación distinta.
Requisitos
La suscripción no debe estarCANCELED ni COMPLETED: esas devuelven 400 INVALID_STATE
(The subscription status <STATUS> does not support plan changes.). Este endpoint acepta
suscripciones CREATED y PAUSED, que el objeto plan_change de Actualizar suscripción
no acepta.
En ambos casos se requiere que el plan esté ACTIVE y pertenezca a la cuenta de la suscripción, y
ninguno está disponible para suscripciones facturadas con frequency.execution: MERCHANT.
Asociar una suscripción que no tiene plan requiere además que la cadencia del plan
coincida con la de la suscripción y que el precio resuelto esté en la moneda de la suscripción. La
suscripción no debe estar en un periodo de prueba, no debe tener ya fases de facturación, no debe usar
un billing_date y no debe tener un monto VARIABLE.
La suscripción adopta la secuencia de fases del plan de destino desde su próximo ciclo sin facturar, y esa
secuencia debe caber dentro de los ciclos de facturación restantes de la suscripción. Si la secuencia comienza con una
fase TRIAL que cubre el ciclo en curso, una suscripción ACTIVE pasa a TRIALING en esta
misma llamada; las suscripciones CREATED y PAUSED no se promueven de esta forma. skip_trial no puede
evitarlo: es un indicador exclusivo de cambios de plan a plan.
Cambiar de un plan a otro requiere además que la suscripción tenga al menos
un ciclo de facturación restante y que su ventana de disponibilidad no termine antes de la próxima renovación.
El plan de destino debe aceptar el tipo de método de pago de la suscripción, si restringe
allowed_payment_methods, y la suscripción debe tener un método de pago almacenado en el vault. La
cadencia y el precio del plan de destino se aplican tal como están definidos en ese plan.
Si la suscripción tenía un cambio programado pendiente, esta llamada lo descarta sin
un webhook subscription.plan_change_canceled; la suscripción de reemplazo comienza con
pending_plan_change: null.
Errores
200 sin efecto. La misma intención expresada
mediante el objeto plan_change de Actualizar suscripción
se rechaza con 422 SAME_PLAN.Autorizaciones
Cuerpo
Solo para cambios de plan a plan. Cuando es true, la suscripción de reemplazo no adopta las fases de prueba o introductorias del plan de destino: factura el precio regular de ese plan desde su primer cobro y su estado sigue siendo ACTIVE en lugar de pasar a TRIALING. Úsalo para evitar que los suscriptores obtengan una prueba nueva al cambiar de plan. Enviar true en una suscripción que no está en un plan devuelve 400; false y omitir el indicador son equivalentes y siempre se aceptan.
true
Respuesta
200
Inicio del período de facturación en el que está la suscripción actualmente, una cadencia antes de current_period_end. Dentro de una prueba o de cualquier otra fase del plan, sigue la cadencia de esa fase. Una suscripción terminal (CANCELED o COMPLETED) conserva su ventana final en lugar de pasar a null. Es null solo para una suscripción sin cadencia recurrente. Siempre se devuelve junto con current_period_end.
"2023-01-16T20:00:00.912480Z"
La política de reintentos que se aplica cuando se rechaza un cobro recurrente. Consulta Reintentos.
El enriquecimiento opcional de la orden enviada en la creación, devuelto tal cual. Consulta El objeto Suscripción para ver su estructura completa.
Qué desencadenó la cancelación: MERCHANT, SYSTEM, PLAN_CHANGE o RETRIES_EXHAUSTED. Solo se define una vez que la suscripción llega a CANCELED; null en caso contrario. Trátalo como un valor abierto: maneja los valores no reconocidos de forma adecuada.
"MERCHANT"
Las definiciones de fases del plan vinculado, tal como las declara el plan, incluida la fase terminal REGULAR. Solo está presente en suscripciones vinculadas a un plan que tiene fases. Esta es la escalera propia del plan, no la instantánea de este suscriptor: para lo que se fijó para esta suscripción en la creación, usa billing_phases.
Cuándo la fase indicada por current_phase pasa a la siguiente: para una suscripción en su prueba, cuándo cambia al precio regular. Es el fin del último período de facturación que cubre la fase, así que en el último período de una prueba es igual a current_period_end. Es null para una suscripción sin plan y para una que ya salió de la escalera de fases.
"2023-03-16T20:00:00.786342Z"
Solo está presente en suscripciones vinculadas a un plan cuyo plan tiene fases. Contiene únicamente las fases TRIAL iniciales, capturadas en la creación; la fase terminal REGULAR nunca se incluye, ya que su precio no se fija y se resuelve a partir del plan en cada facturación. current_phase: "REGULAR" es la señal de que la escalera se agotó.
La regla de reembolso almacenada que se usa para resolver un reembolso de cancelación CUSTOM cuando la solicitud de cancelación no envía su propio refund_amount. Solo está presente cuando hay una configurada; se omite, no es null, en caso contrario. Disponible para las organizaciones habilitadas; contacta a Yuno.
Cuándo está programado que la suscripción se reanude automáticamente. Solo está presente en una suscripción actualmente pausada con una duración (pause_cycles o pause_until enviados al pausar); está ausente, no es null, en cualquier otra lectura.
"2026-10-15T15:54:22.780166Z"