FLUJOS DE CANCELACIÓNPADDLE

Cómo añadir un flujo de cancelación a Paddle Billing

Cómo funciona la cancelación en Paddle Billing: la API de cancelación, cambios programados, pausa y reanudación, descuentos, webhooks y dónde poner retención.

Publicado el 7 min de lectura

Cómo añadir un flujo de cancelación a Paddle Billing

Un flujo de cancelación es el paso corto entre “quiero cancelar” y la cancelación en sí: preguntar por qué, ofrecer algo que encaje con el motivo y cancelar limpiamente si el cliente sigue queriendo irse. Esta guía explica cómo funciona la cancelación en Paddle Billing, qué ofrece Paddle de forma nativa y cómo construir tu propio paso de retención sobre su API.

Se limita a la documentación para desarrolladores de Paddle: cancelar una suscripción, pausar una suscripción, reanudar una suscripción, modificar una suscripción, descuentos, provisión del acceso y webhooks, el portal del cliente y las Cancellation Flows (todas consultadas en noviembre de 2026). Trata de Paddle Billing, no de Paddle Classic, cuya API es distinta.

Paddle es el merchant of record

Una cosa que hay que tener presente todo el tiempo: Paddle es el merchant of record de tus ventas. Vende a tu cliente, gestiona los impuestos y, según Paddle, se encarga del soporte de facturación y de los contracargos. Eso significa que la relación de pago es entre el cliente y Paddle. Tu flujo de cancelación debe cambiar las suscripciones solo mediante la API de Paddle o las propias herramientas de Paddle, nunca intentando detener los pagos de otra forma.

Cómo funciona la cancelación en Paddle Billing

Paddle te da tres lugares donde se puede cancelar una suscripción.

1. La API de cancelación

Cancelas con POST /subscriptions/{subscription_id}/cancel. El campo effective_from decide cuándo:

effective_from Qué pasa
next_billing_period (por defecto, también lo que hace un cuerpo vacío) Paddle añade un scheduled_change con la acción cancel. La suscripción sigue activa hasta su próxima fecha de facturación, y next_billed_at pasa a null
immediately El estado pasa a canceled de inmediato y se dispara subscription.canceled

Paddle documenta algunos límites en la página de cancelación:

  • No puedes cancelar ni pausar en los 30 minutos anteriores a la próxima fecha de facturación.
  • Una cancelación programada puede quitarse modificando la suscripción con scheduled_change en null. Así es como se “deshace” una cancelación antes de que se haga efectiva.
  • Una suscripción cancelada no puede restablecerse. Un cliente que vuelve necesita una suscripción nueva, lo que importa para el win-back.
  • Una suscripción en pausa solo puede cancelarse con effective_from: immediately.

2. El portal del cliente

El portal del cliente de Paddle permite a los clientes cancelar y actualizar sus datos de pago. La documentación de Paddle dice que la pausa no está disponible en el portal, así que una oferta de pausa tiene que venir de tu app o de las Cancellation Flows de Paddle.

3. Las Cancellation Flows de Paddle

Paddle tiene una función nativa justo para esto, que forma parte de Paddle Retain. La configuras en Retain › Cancellation Flows (guía de configuración). Pide un motivo de cancelación y puede ofrecer una pausa, un cambio de plan, contactar con soporte o un descuento por tiempo limitado. Según el changelog de enero de 2026 de Paddle, una vez configurado, el flujo se ejecuta automáticamente cuando los clientes cancelan en el portal del cliente o mediante los enlaces de cancelación de los correos de suscripción de Paddle. En tu propia app lo inicias con Paddle.Retain.initCancellationFlow(), que devuelve un estado como retained, aborted o chose_to_cancel. Un changelog de septiembre de 2026 añade las pruebas en sandbox mediante el portal del cliente, mientras que los flujos iniciados con initCancellationFlow() siguen funcionando solo en cuentas live.

Para que quede claro: si lo único que necesitas es una encuesta de motivos y una oferta estándar dentro de Paddle, esta función nativa puede bastar, y Paddle la incluye sin coste adicional para los clientes de Paddle Billing. El resto de esta guía es para cuando quieres tu propio flujo, tu propio diseño u ofertas que dependen de datos que Paddle no tiene.

Las ofertas de retención que admite la API de Paddle

Pausa

POST /subscriptions/{subscription_id}/pause pausa una suscripción (guía). Acepta effective_from (next_billing_period o immediately) y una fecha opcional resume_at. Una pausa en el próximo periodo de facturación crea un cambio programado; el estado pasa a paused cuando se hace efectiva.

Para que un cliente vuelva antes, POST /subscriptions/{subscription_id}/resume solo funciona con suscripciones en pausa. El campo on_resume decide la facturación: por defecto Paddle empieza un periodo de facturación nuevo y cobra de inmediato; continue_existing_billing_period mantiene en su lugar el periodo antiguo. Paddle también cancela las transacciones de renovación impagadas cuando se pausa una suscripción, para no cobrar dos veces periodos que se solapan.

Descuento

Crea el descuento una vez con POST /discounts. Para una oferta de retención como “50% de descuento durante 3 meses”, fija recur en true y maximum_recurring_intervals en el número de periodos de facturación. Después aplícalo a la suscripción con PATCH /subscriptions/{subscription_id}, pasando un objeto discount con el ID del descuento y un effective_from en next_billing_period o immediately (modificar una suscripción). Enviar discount: null lo quita. Paddle indica que las renovaciones y los cambios a mitad de ciclo no cuentan como nuevos canjes.

Cambio de plan

Una bajada de plan también es una modificación de la suscripción: sustituye los elementos por el precio más barato. Cuando cambias los elementos o la fecha de facturación, Paddle exige proration_billing_mode. Usa el endpoint de vista previa para mostrar al cliente lo que pagará antes de confirmar.

Construir tu propio flujo de cancelación sobre Paddle

  1. Pon el punto de entrada de la cancelación en tu app. Enlaza “Cancelar suscripción” a tu flujo, no directamente a la llamada a la API. Mantén también disponible el portal del cliente; es la propia vía de Paddle y los clientes pueden usarla.
  2. Haz una sola pregunta: por qué. Usa una lista corta de motivos más “Otro” con un campo de texto libre. Guarda la respuesta con el ID de la suscripción.
  3. Muestra una oferta que encaje con el motivo. “Demasiado caro” encaja con un descuento o un plan más barato. “No lo uso ahora mismo” encaja con una pausa con fecha resume_at. “Falta una función” o “Demasiado complejo” encaja con una conversación con soporte. No acumules ofertas.
  4. Mantén “Cancelar ahora” visible en cada paso. El cliente debe poder terminar la cancelación en cualquier momento sin aceptar una oferta. Es una cuestión de confianza y, en varios lugares, de ley.
  5. Llama a Paddle según el resultado. Descuento: PATCH de la suscripción con el descuento. Pausa: POST .../pause. Cambio de plan: PATCH de los elementos después de una vista previa. Cancelación: POST .../cancel con effective_from: next_billing_period, para que el cliente conserve lo que pagó.
  6. Confirma lo que pasa después. Dile al cliente la fecha en que termina el acceso o la fecha en que termina la pausa. Léela de la suscripción que devuelve Paddle en lugar de calcularla tú.
  7. Déjale cambiar de opinión. Hasta que la cancelación programada se haga efectiva, un botón “Mantener mi suscripción” puede quitar el scheduled_change.

Webhooks que escuchar

La guía de provisión del acceso de Paddle recomienda subscription.created y subscription.updated como eventos principales, porque subscription.updated cubre renovaciones, cambios de plan, pausas, reanudaciones y cancelaciones. Algunos eventos dedicados son útiles como señales claras:

Evento Cuándo se dispara
subscription.updated Cualquier cambio, incluida la programación de una cancelación
subscription.canceled El estado pasa a canceled: de inmediato, o en la fecha de facturación si la cancelación estaba programada
subscription.past_due La suscripción pasa a impagada tras una renovación fallida

Las pausas y las reanudaciones también llegan por subscription.updated, con el estado pasando a paused o saliendo de él; consulta la referencia de webhooks de Paddle para ver los eventos dedicados disponibles en tu versión de la API.

Dos detalles de la documentación de Paddle: con una cancelación programada, mantén el acceso hasta la fecha efectiva del cambio programado; y deduplica por event_id y compara occurred_at, porque los eventos pueden llegar desordenados. El payload de subscription.canceled no incluye management_urls.

Después de la cancelación: el win-back

Como Paddle no puede restablecer una suscripción cancelada, una oferta de win-back tiene que llevar a un checkout nuevo. Guarda el motivo de cancelación que recogiste, espera un tiempo razonable y envía una oferta que responda a ese motivo: una función nueva para “faltan funciones”, un precio más bajo para “demasiado caro”. Envía al cliente a un checkout con el descuento ya aplicado.

Hacerlo con NoChurn

NoChurn lee tus suscripciones y eventos de Paddle y añade un flujo de cancelación con motivos, ofertas (descuento, pausa, cambio de plan) y una cancelación en un clic que sigue visible en cada paso, alojado o headless mediante la API. Las ofertas aceptadas y las cancelaciones se aplican en Paddle, y Paddle sigue siendo el merchant of record: conserva el checkout, los pagos, la recuperación de pagos, los impuestos y el portal del cliente. Las disputas las gestiona Paddle y se muestran en NoChurn en solo lectura. NoChurn también envía correos de win-back los días 30, 60 y 90 según el motivo de cancelación, y es gratis por debajo de 300 € de MRR. Consulta NoChurn + Paddle.

PROMPT

Read https://www.nochurn.sh/llms.txt,
then follow https://docs.nochurn.sh/quickstart/
to add NoChurn to this app. Use a test key
(nc_test_…) until I say we go live.

Deja de perder ingresos.

  • Gratis hasta 300 € de MRR
  • Sin tarjeta
  • Listo en 10 minutos
  • Sin comisión