Recovering failed Lemon Squeezy payments

Events that matter

subscription_payment_failed

A renewal payment was declined.

subscription_past_due

The subscription entered the grace window.

subscription_payment_success

Payment recovered — stop outreach.

subscription_expired

The grace window closed; the customer churned.

Setting it up

1. 1

   Add the webhook

   Create a webhook in Lemon Squeezy settings pointing at your RRLabs endpoint and select the subscription payment events.

2. 2

   Verify the HMAC

   Every payload carries an X-Signature header verified against the signing secret before processing.

3. 3

   Link to the customer portal

   Follow-ups link to the Lemon Squeezy customer portal so card updates happen inside their hosted flow.

4. 4

   Close the loop

   subscription_payment_success resolves the attempt and stops queued messages.

Consume Lemon Squeezy subscription webhooks

// Lemon Squeezy → Settings → Webhooks
// Verify the X-Signature HMAC against your signing secret before parsing.
const event = JSON.parse(rawBody);
const name = event.meta?.event_name;
const attrs = event.data?.attributes ?? {};

if (name === "subscription_payment_failed") {
  await rrlabs.enqueueRecovery({
    provider: "lemonsqueezy",
    externalId: String(event.data.id),
    customerEmail: attrs.user_email,
    amountCents: Number(attrs.total ?? 0),
    currency: attrs.currency,
  });
}

if (name === "subscription_payment_success") {
  await rrlabs.closeRecovery({ provider: "lemonsqueezy", externalId: String(event.data.id) });
}

Manual recovery vs. automated recovery

Frequently asked questions