Recovering failed Shopify payments

Events that matter

checkouts/update

A checkout was started and not completed.

orders/paid

The order completed — used to stop follow-ups.

orders/cancelled

The order was cancelled and should be excluded.

Setting it up

1. 1

   Register the webhooks

   Subscribe your RRLabs endpoint to checkout and order topics from the Shopify admin or app configuration.

2. 2

   Separate the causes

   Checkouts that reached payment and failed are treated as recovery; checkouts abandoned earlier are treated as nurture.

3. 3

   Pick the channel

   WhatsApp or SMS where the shopper opted in, email otherwise.

4. 4

   Suppress on success

   orders/paid cancels any queued follow-up for that checkout.

Handle checkouts/update and orders/paid

// Shopify webhook topics: checkouts/update, orders/paid, orders/cancelled
const topic = request.headers.get("x-shopify-topic");
const payload = JSON.parse(rawBody); // verify X-Shopify-Hmac-Sha256 first

if (topic === "checkouts/update" && !payload.completed_at) {
  await rrlabs.enqueueRecovery({
    provider: "shopify",
    externalId: String(payload.id),
    customerEmail: payload.email,
    customerPhone: payload.phone ?? payload.shipping_address?.phone,
    amountCents: Math.round(Number(payload.total_price) * 100),
    currency: payload.currency,
  });
}

if (topic === "orders/paid" || topic === "orders/cancelled") {
  await rrlabs.closeRecovery({ provider: "shopify", externalId: String(payload.checkout_id) });
}

Manual recovery vs. automated recovery

Frequently asked questions