Saltar al contenido principal
POST
Al llamar a este endpoint, el status de la suscripción cambia a PAUSED. Este estado puede cambiar a ACTIVE o CANCELED.

Pausar por un tiempo determinado

Una pausa es indefinida por defecto: la suscripción permanece PAUSED hasta que la reanudes. Enviar un cuerpo con una duración programa la reanudación por adelantado, y la suscripción vuelve por sí sola cuando llega ese momento. Indica la duración de una de dos formas, nunca de ambas:
  • pause_cycles: un entero de 1 a 3, contado desde la pausa en la frecuencia propia de la suscripción.
  • pause_until: un instante RFC 3339. Debe estar en el futuro y caer antes de availability.finish_at cuando la suscripción lo tenga.
billing_cycle_behavior es opcional y define la fecha de facturación cuando la suscripción se reanuda, con los mismos significados de KEEP/RESTART que en Reanudar suscripción: KEEP (el valor predeterminado) mantiene la fecha de facturación original, RESTART la vuelve a anclar desde la reanudación. Enviarlo sin pause_cycles ni pause_until es válido: es una pausa indefinida que solo registra el comportamiento para cuando la suscripción se reanude más adelante. reason es una cadena de texto libre opcional, de 255 caracteres como máximo, que se almacena en el campo reason de la suscripción. Un GET posterior sobre la suscripción lo devuelve, y permanece hasta que algo más lo sobrescribe, por ejemplo una reanudación que envía su propio reason.
pause_cycles se resuelve una sola vez, en el momento de la pausa: el instante resuelto es el instante de la pausa más pause_cycles × la frecuencia de la suscripción. A partir de entonces, la suscripción lleva ese instante como pause_until en cada lectura posterior mientras siga pausada: una pausa indicada en ciclos y una indicada como fecha son indistinguibles después. Por ejemplo, { "pause_cycles": 1 } en una suscripción mensual pausada en 2026-09-15T15:54:18Z se resuelve como pause_until: "2026-10-15T15:54:22.780166Z".

Qué sucede mientras está pausada y cuándo vuelve

No se cobra ningún ciclo durante la pausa. Mientras una duración está en curso, la suscripción lleva pause_until en cada lectura; vuelve por sí sola al estado con el que estaba facturando, dentro de aproximadamente un minuto de ese instante, y llega un webhook subscription.resume con resume_reason: SCHEDULED. Una reanudación manual antes de ese instante cancela la programación: llama tú mismo a Reanudar suscripción en cualquier momento para terminar la pausa antes. Si la reanudación automática no se puede completar después de sus reintentos, la suscripción permanece PAUSED y se envía en su lugar un evento subscription.auto_resume_failed.
DisponibilidadPausar por un tiempo determinado y el campo reason están disponibles para las organizaciones habilitadas para ello; contacta a Yuno.

Errores

Enviar la solicitud sin cuerpo es una pausa indefinida y ninguna de las condiciones anteriores la rechaza.

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
pause_cycles
integer

Pausa durante esta cantidad de ciclos de facturación propios de la suscripción, a partir de la pausa. Se resuelve una sola vez, en la pausa, en un pause_until almacenado. No se puede combinar con pause_until.

Rango requerido: 1 <= x <= 3
Ejemplo:

1

pause_until
string<date-time>

Pausa hasta este instante RFC 3339. Debe estar en el futuro y antes de availability.finish_at. No se puede combinar con pause_cycles.

Ejemplo:

"2026-09-22T15:47:04.964Z"

billing_cycle_behavior
enum<string>

Qué ocurre con el ancla de facturación cuando la suscripción se reanuda (manual o automáticamente). KEEP (por defecto): el ancla original avanza por los períodos completos que se perdió. RESTART: el ancla se reubica en el momento de la reanudación. Enviarlo sin pause_cycles ni pause_until se acepta: es una pausa sin límite que solo registra el comportamiento para cuando la suscripción se reanude más adelante.

Opciones disponibles:
KEEP,
RESTART
Ejemplo:

"RESTART"

reason
string

Motivo libre de la pausa, guardado en el campo reason de la suscripción. Máximo 255 caracteres; un valor en blanco se trata como ausente.

Maximum string length: 255
Ejemplo:

"customer requested a break"

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:

"PAUSED"

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.