Saltar al contenido principal
POST
Llamar a este endpoint reactivará una suscripción. Cambiará una suscripción con status PAUSED de vuelta al estado con el que se estaba facturando: ACTIVE, o TRIALING si aún está dentro de una fase de prueba. También puedes enviar reason, una cadena de texto libre opcional de máximo 255 caracteres, que se almacena en el campo reason de la suscripción. Sobrescribe cualquier reason que haya registrado una pausa anterior.
Elegir qué ocurre con la fecha de facturaciónbilling_cycle_behavior es un campo opcional en esta llamada. Decide qué ocurre con el ancla de facturación (la fecha en billing_cycles.next_at) cuando la suscripción se reanuda:
  • KEEP: se conserva la fecha de facturación original. Si venció mientras la suscripción estaba en pausa, avanza por periodos de facturación completos hasta quedar en el futuro.
  • RESTART: el ciclo se vuelve a anclar al momento de la reanudación, más la frecuencia de la suscripción.
Si omites el campo, se aplica el billing_cycle_behavior que se almacenó en la pausa, ya sea definido explícitamente allí o registrado como KEEP de forma predeterminada. Un valor explícito en esta llamada siempre prevalece sobre lo que almacenó la pausa. Una suscripción pausada antes de que esta función se habilitara para tu organización no tiene nada almacenado, y una reanudación sin cuerpo en una de ellas conserva el comportamiento predeterminado anterior: una fecha de facturación que aún está en el futuro no se modifica, y una que ya pasó se mueve un periodo de facturación a partir de la reanudación.No se emite ningún cobro durante la llamada en ninguno de estos casos. billing_cycle_behavior es solo de escritura: se acepta en la solicitud y nunca se devuelve en ninguna respuesta.
Disponibilidadbilling_cycle_behavior está disponible para las organizaciones habilitadas; contacta a Yuno. Para una organización que aún no está habilitada, enviar el campo devuelve 400: "billing_cycle_behavior is not enabled for this organization."

Comparación de KEEP y RESTART

Una suscripción con un ancla de facturación futura se reanuda con cada valor:
Por ejemplo, reanudar una suscripción mensual el día 15 con RESTART mueve billing_cycles.next_at un mes hacia adelante y establece frequency.monthly_billing_day en 15, tanto en la cadena directa del motor como en la del comercio. Una suscripción que ya declara un monthly_billing_day lo conserva: RESTART vuelve a anclar la fecha, pero no mueve el día en que cae.
RESTART y el día de facturación mensualEn una suscripción mensual creada sin un frequency.monthly_billing_day explícito, RESTART establece ese campo con el día del reinicio, y cada renovación futura lo lee. Una suscripción que ya declara un día de facturación lo conserva: la fecha no se mueve al día del reinicio, solo se vuelve a anclar la hora del día. frequency.monthly_billing_day se devuelve en el objeto de suscripción, por lo que el valor en el que se fijó un reinicio se puede leer desde cualquier respuesta de suscripción.La misma regla se aplica a un RESTART en Actualizar suscripción: es una sola regla, en ambos endpoints.
El webhook subscription.resume se dispara una vez y lleva resume_reason: MERCHANT cuando la reanudación la llamas tú mismo.

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>

KEEP (por defecto cuando se omite): el ancla original avanza por los períodos completos que se perdió durante la pausa. RESTART: reubica el próximo cobro en ahora, más la frecuencia de la suscripción (regla del día de facturación mensual igual que en Update). En una pausa que almacenó su propio billing_cycle_behavior (definido en la llamada de pausa), omitir este campo aplica el comportamiento almacenado en la pausa; un valor explícito aquí siempre prevalece. Solo escritura: nunca se repite en ninguna respuesta.

Opciones disponibles:
KEEP,
RESTART
Ejemplo:

"KEEP"

reason
string

Motivo libre de la reanudación, escrito en el campo reason de la suscripción a partir del cuerpo de esta llamada (null cuando el cuerpo lo omite, incluso si la pausa había registrado uno). Máximo 255 caracteres; un valor en blanco se trata como ausente.

Maximum string length: 255
Ejemplo:

"customer is back"

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"

merchant_reference
string
Ejemplo:

"001_marzo_23"

status
string
Ejemplo:

"ACTIVE"

subscription_plan_id
string
Ejemplo:

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

amount
object
frequency
object
billing_cycles
object
customer_payer
object
payment_method
object

Método de pago que cobra la suscripción. Un único objeto, no una lista.

availability
object
metadata
object[] | null
payments
string[]

Lista de IDs de pago creados por la suscripción. Se omite de la respuesta cuando la suscripción no tiene pagos.

created_at
string
Ejemplo:

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

updated_at
string
Ejemplo:

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

country
string

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

Ejemplo:

"US"

soft_descriptor
string | null

Descriptor suave.

Ejemplo:

"ACME SUBSCRIPTION"

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.

retries
object | null

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

trial_period
object

Período de prueba.

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

subscription_agreement_id
string | null

ID del acuerdo de suscripción.

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.

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.