Saltar al contenido principal
POST
Llamar a este endpoint con un cuerpo vacío (o sin cuerpo) cancela la suscripción de inmediato, cambiando su status a CANCELED. Esto no cambió y sigue siendo definitivo: una vez inmediata, no se puede revertir. Puedes cancelar desde CREATED, ACTIVE, TRIALING, PAST_DUE y PAUSED. COMPLETED y CANCELED son estados terminales, por lo que cancelar desde cualquiera de ellos devuelve 400 INVALID_STATE, incluida una segunda cancelación sobre una suscripción que ya está cancelada. Consulta Estado de la suscripción.

Reembolso en la cancelación inmediata

Solo organizaciones en la lista de permitidosLa cotización de reembolsos se habilita por organización, independientemente de la cancelación programada. Si tus llamadas devuelven 400 "Refund quote is not enabled for this organization.", contacta a tu representante de Yuno para que la habilite.
Envía un modo refund junto con una cancelación inmediata (sin schedule) para que Yuno calcule una cotización de reembolso para el ciclo de facturación actual. Yuno solo calcula la cotización, nunca mueve dinero. refund.execution en la respuesta siempre es "MERCHANT": tú ejecutas el reembolso por tu propio canal de pago, usando el monto cotizado como dato de entrada.
Cancel with a prorated refund
refund no se puede combinar con schedule: enviar ambos, o enviar refund junto con "schedule": null, se rechaza con 400 antes de escribir nada. refund: NONE, u omitir refund por completo, sigue funcionando con normalidad junto con schedule.

La base del reembolso

Todos los modos de reembolso se calculan sobre la misma base: el pago capturado más reciente de la suscripción, nunca el precio de lista de la propia suscripción ni una estimación. Para un ciclo que incluyó una promoción, estos montos son el neto pagado después del descuento, y basis.charged_amount lo muestra. Si el ciclo actual no tiene ningún pago capturado (un rechazo, un pago aún pendiente, o un vacío), PRORATED, FULL y CUSTOM devuelven 400 REFUND_NOT_AVAILABLE, excepto en una fase genuina de $0 (una fase de prueba o promocional sin ningún cobro) o un ciclo cubierto por completo por una promoción, que devuelve 200 con amount: 0.00. No hay nada que reembolsar ahí, pero eso no es un error. Una suscripción PAST_DUE no tiene ningún pago capturado para el ciclo en curso, así que se aplica la misma regla: refund: NONE (o un refund ausente) sigue cancelando con normalidad, pero cualquier otro modo devuelve 400 REFUND_NOT_AVAILABLE con current_status: "PAST_DUE".

PRORATED

Reembolsa los días no usados del ciclo actual, usando aritmética de fechas de calendario, nunca horas ni minutos:
  • period_start: la fecha en que se cobró el último pago capturado.
  • period_end: la fecha en que termina naturalmente el ciclo actual, limitada a availability.finish_at cuando la suscripción lo tiene y es anterior.
  • unused_days = period_days − used_days, donde used_days cuenta el día en que cancelas como un día completo usado: cancelar a cualquier hora del día 10 de un ciclo de 30 días cuenta igualmente 10 días usados.
  • amount = charged_amount × unused_days / period_days, redondeado HALF_UP a las unidades menores de la moneda.
Por ejemplo, un ciclo de 30 días cobrado por $30.00, cancelado el día 10: 10 días usados, 20 días sin usar, amount = 30.00 × 20/30 = 20.00.
Cancel with a prorated refund — response
Una suscripción facturada por hora o por minuto no tiene una noción significativa de “día”, por lo que PRORATED devuelve allí 400 "proration is not available for sub-daily cadences". FULL y CUSTOM no se ven afectados: ambos siguen funcionando en una cadencia inferior a un día.

FULL

Reembolsa el basis.charged_amount completo del ciclo actual: amount siempre es igual a basis.charged_amount exactamente, y unused_days es igual a period_days (todo el ciclo se trata como no usado).

CUSTOM

Un reembolso CUSTOM toma su monto de uno de dos lugares, en este orden:
  1. refund_amount en la solicitud de cancelación, si envías uno.
  2. De lo contrario, el refund_rule configurado en la suscripción.
Si no existe ninguno, la cancelación se rechaza con 400 BAD_REQUEST: "refund: CUSTOM requires refund_amount or a configured refund_rule." CUSTOM nunca recurre a un monto calculado. refund_rule se define en Crear o Actualizar y se describe en el objeto Subscription.
Cancel G — the request's refund_amount wins over the configured refund_rule
Cancel H — no refund_amount sent, the configured refund_rule wins
DisponibilidadUn refund_rule configurado está disponible para las organizaciones habilitadas; contacta a Yuno. Para una organización que aún no está habilitada, CUSTOM se comporta exactamente como hoy: refund_amount en la solicitud es obligatorio y nunca se puede configurar un refund_rule para esa organización en primer lugar.
Envía refund_amount junto con "refund": "CUSTOM" para reembolsar un monto específico en lugar de uno calculado o basado en una regla:
Cancel with a custom refund amount
amount en la respuesta es tu refund_amount devuelto exactamente igual, sin recalcular ni redondear de nuevo. refund_amount.value debe ser mayor que 0 y no debe superar el monto cobrado del ciclo actual, y refund_amount.currency debe coincidir con la moneda de la propia suscripción.

Leer el objeto refund

refund es null cuando refund fue NONE o se omitió. De lo contrario:

Dónde aparece refund

  • La respuesta 200 de cancelación siempre incluye la clave refund: null cuando no se calculó ninguna cotización, el objeto en caso contrario.
  • GET /v1/subscriptions/{id} y GET /v1/subscriptions?merchant_reference=... también incluyen el refund calculado por última vez, una vez que existe: cancelar con una cotización de reembolso lo persiste, por lo que sigue apareciendo en cada lectura posterior de esa suscripción a través de cualquiera de estos dos.
  • GET /v1/subscriptions (la lista paginada) no incluye refund en ninguna entrada, sin importar si esa suscripción se canceló o no con una cotización: el elemento de la lista es una forma de resumen más pequeña que el objeto de suscripción completo, y refund no es uno de los campos que incluye.
  • El webhook subscription.cancel incluye refund solo cuando realmente se calculó una cotización (PRORATED/FULL/CUSTOM): está ausente, no null, en una cancelación NONE o sin reembolso.

Programar una cancelación en su lugar

Solo organizaciones en la lista de permitidosLa cancelación programada se habilita por organización. Si tus llamadas devuelven 400 "Scheduled cancellation is not enabled for this organization.", contacta a tu representante de Yuno para que la habilite.
Envía un objeto schedule para diferir la cancelación en lugar de aplicarla ahora. La suscripción permanece en su estado actual, y la facturación continúa con normalidad, hasta que se ejecute la programación.
Schedule after 3 more billing cycles
Schedule for a specific date
schedule acepta exactamente uno de: Enviar ambos o ninguno devuelve 400. Una suscripción PIX_AUTOMATIC facturada con frequency.execution: MERCHANT no puede programar una cancelación: prográmala como at o after_cycles en un tipo de método de pago distinto, o cancela de inmediato.

Comportamiento mientras se ejecutan los reintentos

past_due_behavior se devuelve en cancel_scheduled, pendiente de confirmación de productoActualmente el motor registra el past_due_behavior que se resolvió para la programación (el valor explícito o el valor predeterminado EXHAUST_RETRIES) en el campo cancel_scheduled.past_due_behavior de cada respuesta. Trata este valor devuelto como provisional hasta que producto lo confirme como el contrato externo previsto: puede cambiar.
past_due_behavior controla qué hace una cancelación programada si la suscripción está en PAST_DUE cuando la programación se ejecutaría de otro modo:
Schedule and skip retries if PAST_DUE when it fires
Independientemente de past_due_behavior, cancelar una suscripción PAST_DUE, ya sea de inmediato o porque una programación venció, nunca genera un error y siempre detiene los reintentos de ese ciclo. Consulta Estado de la suscripción y Reintentos.
El manejo de reembolsos solo está disponible en una cancelación inmediata; consulta Reembolso en la cancelación inmediata. No se incluye con la cancelación programada: una solicitud con schedule no puede incluir también un modo refund.

Deshacer una cancelación programada

Envía "schedule": null para borrar una programación pendiente. La suscripción no se ve afectada de otro modo: sin cambio de estado ni cobro.
Undo a scheduled cancellation
Enviar "schedule": null cuando no hay nada programado no hace nada: 200, cancel_scheduled sigue siendo null y no se envía ningún webhook. Cuando se borra una programación, se envía en su lugar subscription.cancel_schedule_canceled.

Leer el resultado

La respuesta incluye la misma forma de Subscription que cualquier otro endpoint de suscripciones. Cuatro campos son relevantes aquí:
  • cancel_scheduled: null cuando no hay ninguna cancelación pendiente; de lo contrario, el mode de la programación, after_cycles/at, requested_at y past_due_behavior.
  • retries.stopped, retries.attempts_made, retries.outcome, retries.next_retry_at: se completan siempre que la suscripción está en PAST_DUE o tiene un cancel_scheduled pendiente; se omiten en los demás casos.
  • unpaid_cycle: está presente cuando el ciclo de facturación actual está en PAST_DUE y no se ha saldado.
  • refund: null (o ausente en lecturas que no son de cancelación) cuando no se calculó ninguna cotización de reembolso; de lo contrario, el monto cotizado y su base. Consulta Reembolso en la cancelación inmediata.
La persistencia de retries y unpaid_cycle después de la cancelación está pendiente de confirmación de productoAmbos campos se calculan a partir del estado en vivo de la suscripción al momento de la solicitud. Si un GET /v1/subscriptions/{id} emitido después de que la suscripción llega a CANCELED sigue mostrando la instantánea de reintentos o el ciclo impago del ciclo que estaba en curso, o los omite una vez terminal, aún no está confirmado como un contrato estable: verifica con una respuesta en vivo antes de depender de ello.
Consulta el objeto Subscription para ver la referencia completa de campos.

Programar una cancelación en una suscripción pausada

Una suscripción pausada aún se puede programar para cancelación. schedule.after_cycles se rechaza mientras la suscripción está en PAUSED, porque una pausa congela el reloj de facturación y no hay ningún límite de ciclo desde el cual contar:
400 — after_cycles on a paused subscription
schedule.at no tiene esa restricción: no necesita un reloj de ciclos, por lo que se acepta con normalidad en una suscripción PAUSED. Consulta Pausar suscripción.

Webhooks

  • subscription.cancel_scheduled: se envía cuando se programa una cancelación mediante este endpoint.
  • subscription.cancel_schedule_canceled: se envía cuando se deshace una cancelación programada pendiente mediante "schedule": null.
Una cancelación inmediata (cuerpo vacío, o una programación que vence) sigue emitiendo subscription.cancel como antes: la programación emite sus propios eventos solo para las acciones de programar y deshacer. El payload de subscription.cancel también incluye refund, siguiendo la misma regla que la respuesta de cancelación: está presente solo cuando realmente se calculó una cotización (PRORATED/FULL/CUSTOM) y ausente en una cancelación NONE o sin reembolso.

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
refund
string

NONE (predeterminado), PRORATED, FULL o CUSTOM. Calcula una cotización de reembolso para el ciclo de facturación actual en una cancelación inmediata. No se puede combinar con schedule.

Ejemplo:

"PRORATED"

refund_amount
object

Obligatorio, y solo se permite, cuando refund es CUSTOM. No debe superar el monto cobrado del ciclo actual.

schedule
object | null

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:

"CANCELED"

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.

retries
object
unpaid_cycle
object

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

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.

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.

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"