Cómo gestiona Lemon Squeezy los pagos de suscripción fallidos
Qué pasa en Lemon Squeezy cuando falla una renovación: estados past_due y unpaid, los cuatro reintentos, correos de recuperación, webhooks y qué añadir.

Cuando falla la renovación de una suscripción en Lemon Squeezy, pasan muchas cosas sin que tengas que hacer nada: se reintenta el cobro, el cliente recibe correos y la suscripción pasa por varios estados antes de terminar. Saber exactamente qué hace Lemon Squeezy, y qué te deja a ti, marca la diferencia entre un cliente que desaparece sin hacer ruido y uno que actualiza su tarjeta.
Esta guía recorre ese ciclo paso a paso y después da consejos prácticos que puedes aplicar en tu propia app. Se limita a la documentación de Lemon Squeezy: la página de ayuda Recovery and Dunning, la referencia del objeto Subscription, los tipos de eventos de webhook y la página de ayuda de Subscriptions (todas consultadas en noviembre de 2026). Cuando la documentación no dice algo, lo indicamos.
El ciclo de un pago fallido en Lemon Squeezy
Lemon Squeezy es un merchant of record: cobra al cliente, hace los reintentos y envía los correos de facturación. Tu trabajo consiste sobre todo en reaccionar a los cambios de estado en tu app.
Paso 1: la renovación falla y la suscripción pasa a past_due
Según la referencia del objeto Subscription, cuando falla un pago de renovación el estado de la suscripción pasa a past_due. La suscripción pasa entonces por 4 reintentos de pago a lo largo de 2 semanas. Si uno de esos reintentos funciona, el estado vuelve a active.
La página Recovery and Dunning añade dos detalles:
- Durante los reintentos, la suscripción sigue contando como activa en cuanto al acceso: el cliente sigue usando tu producto.
- Cada intento fallido dispara un correo que pide al cliente que actualice sus datos de facturación.
Paso 2: se agotan los reintentos y la suscripción pasa a unpaid
Si todos los reintentos fallan, el estado pasa a unpaid. Aquí empieza el dunning de Lemon Squeezy. Según la página Recovery and Dunning, los correos de recuperación se envían durante un periodo fijo, y cada uno enlaza a una página donde el cliente puede actualizar sus datos de pago y reactivar la suscripción.
Paso 3: termina el dunning, o la suscripción sigue unpaid
Lo que pasa después depende de tus ajustes de Recovery:
- Puedes fijar un plazo tras el cual la suscripción se cancela automáticamente. Una vez cancelada, el cliente ya no puede reactivarla.
- Puedes dejar la suscripción en
unpaid, lo que permite al cliente reactivarla en cualquier momento. - Si desactivas el dunning, el estado simplemente se queda en
unpaid, y te toca a ti decidir qué significa eso para el acceso.
Cuando termina el dunning, Lemon Squeezy envía subscription_expired, que su página de tipos de eventos describe como un evento que se dispara “una vez completado el dunning de las suscripciones past_due”.
PayPal es distinto
La página Recovery indica que las suscripciones de PayPal siguen otro ritmo de reintentos, con un intento cada 5 días. Si una parte importante de tus clientes paga con PayPal, no supongas que el calendario de las tarjetas se les aplica.
Los estados de un vistazo
| Estado | Qué significa | ¿Debe tener acceso el cliente? |
|---|---|---|
active |
Pagada y al día | Sí |
past_due |
Falló la renovación, reintentos en curso (4 en unas 2 semanas) | Sí, según Lemon Squeezy |
unpaid |
Reintentos agotados, dunning en curso o desactivado | Decides tú; la documentación del ciclo de Lemon Squeezy dice que el acceso solo debería terminar en expired |
cancelled |
Cancelada, en su periodo de gracia hasta ends_at |
Sí, hasta ends_at |
expired |
Terminada | No |
La página de ayuda de Subscriptions dice que los clientes deben mantener el acceso en todos los estados salvo expired. Algunos equipos prefieren restringir funciones mientras está en unpaid; si lo haces, dilo claramente en tu app para que el cliente sepa por qué.
Los webhooks que necesitas
La página de tipos de eventos enumera los eventos de suscripción. Para los pagos fallidos, importan estos cinco:
| Evento | Cuándo se dispara | Contenido |
|---|---|---|
subscription_payment_failed |
Falla un pago de renovación (no el primer pago) | Objeto subscription invoice |
subscription_payment_recovered |
Un pago funciona después de un fallo | Objeto subscription invoice |
subscription_payment_success |
Cualquier pago correcto; siempre se envía junto con subscription_payment_recovered |
Objeto subscription invoice |
subscription_updated |
Cualquier cambio en la suscripción, incluidos los cambios de estado | Objeto subscription |
subscription_expired |
Cuando termina una suscripción cancelada, o al completarse el dunning | Objeto subscription |
Dos cosas a tener en cuenta. Primero, subscription_payment_failed lleva un objeto subscription invoice, no la suscripción en sí, así que normalmente tendrás que obtener la suscripción para leer su estado. Segundo, Lemon Squeezy dice que subscription_updated se dispara con cada cambio después del pago inicial, así que en muchas apps basta con escucharlo y leer status.
La documentación que usamos no describe en estos eventos un campo de motivo de rechazo comparable a los códigos de rechazo de las redes de tarjetas, así que no construyas lógica que dependa de uno sin revisar tus propios payloads.
El enlace para actualizar el pago
Cada objeto subscription tiene un atributo urls con un enlace update_payment_method: una URL prefirmada donde el cliente puede cambiar su tarjeta. La referencia del objeto Subscription dice que estas URL firmadas son válidas durante 24 horas, y la guía de gestión de suscripciones dice lo mismo de los enlaces de recuperación: vuelve a obtener la suscripción para conseguir uno nuevo en lugar de guardarlo.
Eso tiene una consecuencia práctica. Si envías tus propios correos, no pegues un enlace guardado en un correo que podría abrirse tres días después. Enlaza a una página de tu app que obtenga una URL nueva y redirija.
Configurar los ajustes de Recovery
Los correos de recuperación de Lemon Squeezy se configuran en la página de ajustes Recovery de tu tienda. La página Recovery and Dunning dice que puedes activar o desactivar el dunning y editar los correos, los asuntos, el contenido y el calendario de envío, con valores por defecto.
Una configuración sensata:
- Mantén el dunning activado. No cuesta nada y llega a los clientes que nunca abren tu app.
- Reescribe el texto por defecto con tu propio tono. Di qué es el producto, qué pasa si no se actualiza la tarjeta y deja un único botón claro.
- Decide a propósito sobre la cancelación automática. Dejar las suscripciones en
unpaidmantiene abierta la puerta a la reactivación. La cancelación automática te da una fecha de fin limpia. Elige una opción y haz que las reglas de acceso de tu app coincidan. - Pruébalo. El modo test de Lemon Squeezy te permite simular eventos de webhook, así que puedes comprobar cómo reacciona tu app a
past_due,unpaidyexpiredantes de que le pase a un cliente real.
Consejos prácticos que puedes aplicar hoy
El comportamiento integrado de Lemon Squeezy es una buena base. Las carencias están sobre todo en tu lado de la integración.
1. Muestra el problema dentro de tu app
Los correos de facturación se filtran. Cuando una suscripción está en past_due o unpaid, muestra un banner en tu app con un botón hacia tu ruta de “actualizar tarjeta”. Suele ser el momento en que el cliente tiene más probabilidades de actuar, porque ya está usando el producto.
2. Gestiona los estados de forma explícita
Asocia cada estado a una regla de acceso en un único lugar de tu código. Un error frecuente es tratar todo lo que no sea active como “sin acceso”, lo que bloquea a clientes past_due y cancelled que han pagado su periodo actual.
3. Verifica y deduplica los webhooks
Lemon Squeezy firma cada petición con un HMAC en la cabecera X-Signature (firmar peticiones) y reintenta las respuestas distintas de 200 hasta tres veces más con espera exponencial (peticiones de webhook). Verifica la firma sobre el cuerpo sin procesar y haz que tu handler pueda ejecutarse dos veces sin problemas.
4. Envía un mensaje humano
Los correos automáticos cubren la mecánica. Un mensaje corto y sencillo de una persona real (“Tu tarjeta no se ha podido cobrar, aquí tienes el enlace, responde si algo va mal”) suele recibirse de otra forma. Envíalo una vez, hacia el momento en que la suscripción pasa a unpaid, no en cada intento fallido.
5. Mide la recuperación
Cuenta los eventos subscription_payment_failed y subscription_payment_recovered de cada mes. La proporción es tu propia tasa de recuperación, medida con tus datos. Si cambia después de modificar un texto, sabrás que el cambio importó.
Hacerlo con NoChurn
Lemon Squeezy sigue gestionando el pago, los reintentos y sus propios correos de recuperación; NoChurn no sustituye eso. NoChurn lee tus webhooks de Lemon Squeezy, pone cada pago fallido en una sola cronología y puede añadir correos de recuperación escritos por IA que revisas antes de que se envíen. También da a cada cliente un churn score de 0 a 100, y las disputas, que Lemon Squeezy gestiona como merchant of record, aparecen en solo lectura. NoChurn es gratis por debajo de 300 € de MRR, con todas las funciones en todos los planes (tu propio dominio para correos y páginas alojadas como complemento de 14,99 € al mes en cualquier plan). Consulta NoChurn + Lemon Squeezy.