Saltar al contenido principal
POST
Change Subscription Plan
El cambio entra en vigor en la próxima renovaciónNo se realiza ningún cobro cuando llamas a este endpoint, y no se prorratea ni se reembolsa nada. La suscripción sigue facturando según su calendario actual; el precio del nuevo plan se aplica a partir de la fecha de la próxima renovación.

Dos comportamientos, un endpoint

El comportamiento que obtienes depende de si la suscripción ya está en un plan. En el caso de reemplazo, la suscripción original queda 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.
Promociones cuando cambia el planPara una suscripción que ya está en un plan, la promoción original termina con 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.
Guarda el id devuelto después de un cambio de plan a planLa suscripción de reemplazo es una suscripción distinta. Si conservas el id anterior, las llamadas posteriores actuarán sobre una suscripción cancelada.

Webhooks

Un cambio de plan a plan emite tres eventos:
  • subscription.create para la suscripción de reemplazo.
  • subscription.cancel para la original, con cancellation_source: PLAN_CHANGE. No lo cuentes como cancelación de clientes (churn).
  • subscription.plan_changed para la suscripción de reemplazo, con previous_subscription_id definido.
El caso de asociación no emite ninguno de ellos. Su único webhook es un cambio de estado, y solo cuando la secuencia de fases del plan promueve la suscripción a 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. Establece skip_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.
Change plan without granting a new trial
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: Si cambias de plan en suscripciones que ya están en un plan y quieres conservar su 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: Establece 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 devuelve 200 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 estar CANCELED 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

Volver a enviar el plan actual de la suscripción aquí es una operación 200 sin efecto. La misma intención expresada mediante el objeto plan_change de Actualizar suscripción se rechaza con 422 SAME_PLAN.

Autorizaciones

public-api-key
string
header
predeterminado:<Your public-api-key>
requerido
private-secret-key
string
header
predeterminado:<Your private-secret-key>
requerido

Parámetros de ruta

subscription_id
string<uuid>
requerido

Identificador único de una suscripción.

Cuerpo

application/json
plan_id
string<uuid>
requerido

El identificador único del plan al que se moverá la suscripción.

Ejemplo:

"1904911d-5df9-429e-8488-ad41abea1a4d"

skip_trial
boolean
predeterminado:false

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.

Ejemplo:

true

Respuesta

200

id
string
Ejemplo:

"7304911d-5df9-429e-8488-ad41abea1a4c"

name
string
Ejemplo:

"sub_001"

description
string | null
Ejemplo:

"streaming service"

account_id
string
Ejemplo:

"2404911d-5df9-429e-8488-ad41abea1a4b"

country
string

El país de la suscripción (ISO 3166-1 alpha-2).

Ejemplo:

"US"

merchant_reference
string
Ejemplo:

"001_marzo_23"

soft_descriptor
string | null
Ejemplo:

"ACME SUBSCRIPTION"

status
string
Ejemplo:

"ACTIVE"

amount
object
frequency
object
billing_cycles
object
current_period_start
string | null

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.

Ejemplo:

"2023-01-16T20:00:00.912480Z"

current_period_end
string | null

Fin del período de facturación en el que está la suscripción actualmente. Es igual a billing_cycles.next_at. Siempre se devuelve junto con current_period_start.

Ejemplo:

"2023-02-16T20:00:00.786342Z"

billing_date
object | null

Solo está presente en suscripciones facturadas en una fecha fija en lugar de una frecuencia; es mutuamente excluyente con frequency.

customer_payer
object
payment_method
object
availability
object
retries
object | null

La política de reintentos que se aplica cuando se rechaza un cobro recurrente. Consulta Reintentos.

trial_period
object | null
metadata
object[] | null
additional_data
object | null

El enriquecimiento opcional de la orden enviada en la creación, devuelto tal cual. Consulta El objeto Suscripción para ver su estructura completa.

initial_payment_validation
boolean

Indica si la suscripción esperó a que su primer pago fuera exitoso antes de activarse. Es false por defecto.

Ejemplo:

false

reason
string | null

Motivo libre del estado actual de la suscripción, cuando se registró uno; null en caso contrario.

Ejemplo:

"merchant request"

renewal_notification_days
integer | null

Cuántos días antes de la próxima fecha de facturación se envía el webhook subscription.close_to_renewal. null significa que no se envía ninguna notificación de renovación.

Ejemplo:

3

payments
string[]
subscription_agreement_id
string | null
Ejemplo:

"sa_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa"

cancellation_time
string | null

Cuándo se canceló la suscripción. Solo se define una vez que llega a CANCELED; null en caso contrario.

Ejemplo:

"2023-12-16T20:46:54.786342Z"

cancellation_source
string | null

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.

Ejemplo:

"MERCHANT"

ending_time
string | null

Cuándo se completó o expiró la suscripción. Solo se define una vez que llega a COMPLETED; null en caso contrario.

Ejemplo:

"2024-12-16T20:46:54.786342Z"

plan_id
string

Solo está presente cuando la suscripción está vinculada a un plan.

Ejemplo:

"00000000-0000-4000-8000-000000000001"

plan_assigned_at
string

Solo está presente en suscripciones vinculadas a un plan. El momento en que se asoció el plan: en la creación a partir de un plan, en la migración a un plan o en un cambio de plan.

Ejemplo:

"2023-12-16T20:46:54.786342Z"

previous_subscription_id
string | null

Solo está presente cuando esta suscripción se creó por un cambio de plan (cambiar una suscripción existente a un plan diferente).

phases
object[]

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.

current_phase
string

Solo está presente en suscripciones vinculadas a un plan.

Ejemplo:

"REGULAR"

current_phase_end
string | null

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.

Ejemplo:

"2023-03-16T20:00:00.786342Z"

billing_phases
object[]

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ó.

pending_plan_change
object | null

El cambio de plan programado para el próximo ciclo de facturación, o null cuando no hay ninguno pendiente. Programa uno con el bloque plan_change en Update Subscription.

created_at
string
Ejemplo:

"2023-12-16T20:46:54.786342Z"

updated_at
string
Ejemplo:

"2023-12-16T21:00:54.786342Z"

refund_rule
object

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.

pause_until
string

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.

Ejemplo:

"2026-10-15T15:54:22.780166Z"

cancel_scheduled
object | null

null cuando no hay ninguna cancelación pendiente.

refund
object | null

null cuando refund fue NONE o se omitió. Está presente en la respuesta de cancelación y en cada lectura posterior una vez calculado.

unpaid_cycle
object

Solo está presente cuando el ciclo de facturación actual está en PAST_DUE y no se ha liquidado.