Saltar al contenido principal
POST
Usa este endpoint para campañas de recuperación de clientes. Al llamarlo, una suscripción CANCELED o COMPLETED vuelve a ACTIVE (o a TRIALING cuando una fase de prueba cubre el ciclo reactivado), conservando el mismo id y todo su historial de pagos. Nunca se crea una suscripción sucesora y esta llamada nunca define previous_subscription_id. La llamada en sí no genera ningún cobro.
Solo organizaciones en la lista de permitidosLa reactivación se habilita por organización y esto se verifica antes que el estado de la suscripción. Si tus llamadas devuelven 409 "Subscription reactivation is not enabled for this organization.", contacta a tu representante de Yuno para que la habilite.

Qué suscripciones se pueden reactivar

409 — status is not CANCELED or COMPLETED
Una suscripción cuyo availability.finish_at ya pasó se rechaza con 400 INVALID_DATE, sin importar su estado:
400 — availability window already closed

Cuando se agotan los ciclos de facturación

Una suscripción COMPLETED que usó todos los ciclos de billing_cycles.total se rechaza con 409 INVALID_SUBSCRIPTION_STATUS:
409 — no billing cycles left
Envía billing_cycles.total con un valor mayor al actual para subir el límite y reactivar en la misma llamada. Esto no crea una sucesora: sube el límite en la misma suscripción, conservando su id y su historial intactos:
Raise the limit and reactivate
Al enviar billing_cycles.total: Enviar billing_cycles.total para una suscripción que aún tiene ciclos disponibles se acepta de la misma manera: sube el límite, no está restringido a suscripciones agotadas. Un billing_cycles.total: null explícito se trata igual que omitir el campo: el total actual se mantiene sin cambios.

Elegir la próxima fecha de facturación

billing_cycle_behavior es el mismo eje que se usa al reanudar y en los cambios de plan.
En ambos casos la llamada no genera ningún cobro. Un valor no válido devuelve 400 BAD_REQUEST: "billing_cycle_behavior must be one of KEEP, RESTART." Reactivar no tiene validación propia en el gateway: el mismo texto vuelve sin cambios a través del gateway.
RESTART y el día de facturación mensualEn una suscripción mensual que no tenía definido frequency.monthly_billing_day, RESTART lo fija al día de la reactivación, la misma regla que aplican Actualizar suscripción y Reanudar suscripción. Una suscripción que ya declara un día de facturación lo conserva.

El método de pago

El método de pago almacenado se revalida antes de reactivar la suscripción. Si ya no está inscrito, la llamada devuelve 400 PAYMENT_METHOD_STATUS_INVALID y la suscripción no se modifica: la verificación del método de pago se ejecuta antes de escribir el estado:
400 — payment method no longer enrolled

Qué borra la reactivación

Al reactivar una suscripción se borra lo siguiente:
  • cancellation_time
  • cancellation_source
  • ending_time
  • reason
  • cualquier cancelación programada (cancel_scheduled)
  • cualquier pausa programada para terminar por sí sola: una suscripción reactivada nunca conserva pause_until
El webhook subscription.reactivate se envía una sola vez y lleva la suscripción reactivada.

Errores

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
requerido

Identificador único de una suscripción.

Cuerpo

application/json
billing_cycle_behavior
enum<string>

RESTART reubica el próximo cobro en ahora más la frecuencia de la suscripción (y registra frequency.monthly_billing_day en una suscripción mensual que no tenía uno). KEEP u omitido: el ancla almacenada no se modifica mientras siga en el futuro; de lo contrario, avanza a su próxima ocurrencia futura. En ambos casos la llamada no realiza ningún cobro.

Opciones disponibles:
KEEP,
RESTART
Ejemplo:

"RESTART"

billing_cycles
object

Aumenta el límite de ciclos de la suscripción para poder reactivarla. Solo se permite el total anidado.

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