Cancelar suscripción
Cancela una suscripción de inmediato o programa la cancelación para una fecha futura o un ciclo de facturación.
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
400 "Refund quote is not enabled for this organization.", contacta a tu representante de Yuno
para que la habilite.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.
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, ybasis.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 aavailability.finish_atcuando la suscripción lo tiene y es anterior.unused_days = period_days − used_days, dondeused_dayscuenta 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, redondeadoHALF_UPa las unidades menores de la moneda.
$30.00, cancelado el día 10: 10 días usados, 20 días sin usar,
amount = 30.00 × 20/30 = 20.00.
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 elbasis.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 reembolsoCUSTOM toma su monto de uno de dos lugares, en este orden:
refund_amounten la solicitud de cancelación, si envías uno.- De lo contrario, el
refund_ruleconfigurado en la suscripción.
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.
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.refund_amount junto con "refund": "CUSTOM" para reembolsar un monto específico en lugar de uno
calculado o basado en una regla:
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
200de cancelación siempre incluye la claverefund:nullcuando no se calculó ninguna cotización, el objeto en caso contrario. GET /v1/subscriptions/{id}yGET /v1/subscriptions?merchant_reference=...también incluyen elrefundcalculado 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 incluyerefunden 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, yrefundno es uno de los campos que incluye.- El webhook
subscription.cancelincluyerefundsolo cuando realmente se calculó una cotización (PRORATED/FULL/CUSTOM): está ausente, nonull, en una cancelaciónNONEo sin reembolso.
Programar una cancelación en su lugar
400 "Scheduled cancellation is not enabled for this organization.", contacta a tu representante de Yuno para que la
habilite.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 acepta exactamente uno de:
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:
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.
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.
"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:nullcuando no hay ninguna cancelación pendiente; de lo contrario, elmodede la programación,after_cycles/at,requested_atypast_due_behavior.retries.stopped,retries.attempts_made,retries.outcome,retries.next_retry_at: se completan siempre que la suscripción está enPAST_DUEo tiene uncancel_scheduledpendiente; se omiten en los demás casos.unpaid_cycle: está presente cuando el ciclo de facturación actual está enPAST_DUEy 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.
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.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:
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.
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
Cuerpo
Respuesta
200
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.
"2023-01-16T20:00:00.912480Z"
El enriquecimiento opcional de la orden enviada en la creación, devuelto tal cual. Consulta El objeto Suscripción para ver su estructura completa.
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.
"MERCHANT"
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.
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.
"2023-03-16T20:00:00.786342Z"
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ó.
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.
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.
"2026-10-15T15:54:22.780166Z"