PAGOS FALLIDOSLEMON SQUEEZY

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.

Publicado el 7 min de lectura

Cómo gestiona Lemon Squeezy los pagos de suscripción fallidos

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:

  1. Mantén el dunning activado. No cuesta nada y llega a los clientes que nunca abren tu app.
  2. 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.
  3. Decide a propósito sobre la cancelación automática. Dejar las suscripciones en unpaid mantiene 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.
  4. 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, unpaid y expired antes 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.

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