DEV Community: Andras Palinkas

There is no 'abandoned' event: a developer's map of Shopify's abandoned checkout API and webhooks

Andras Palinkas — Tue, 06 Oct 2026 08:57:05 +0000

The first thing most people look for when they start building on Shopify's abandoned checkouts doesn't exist: there is no webhook that fires when a checkout becomes abandoned. That one fact shapes the whole design, so here's the map I wish I'd had on day one — what Shopify actually gives you, what it doesn't, and the two things we learned the hard way while building a cart-recovery app on it.

"Abandoned" is a state, not an event

Shopify's Abandoned Checkouts documentation defines it in one sentence: "A checkout is considered abandoned after the customer has added contact information, but before the customer has completed their purchase."

Nothing fires at the moment of abandonment, because there is no such moment. In practice you subscribe to checkout events, watch for completion, and apply your own delay before treating a checkout as abandoned. The delay is yours to choose — Shopify leaves it entirely to you.

The webhooks

From the webhook topic list, the relevant topics:

Topic	What it tells you
`checkouts/create`	A checkout started. In our tests it fired within seconds of the shopper typing an email address.
`checkouts/update`	Something changed — address, shipping, payment step. Carries `completed_at` once the order is placed.
`checkouts/delete`	The checkout was removed.
`orders/create`	The reliable completion signal: match it to the checkout and cancel any pending reminder.
`carts/create`, `carts/update`	The pre-checkout cart. No contact information, so useful for analytics, not for reaching anyone.

The checkout payload has what a recovery flow needs: an id and token, the cart_token linking it to the earlier cart, email (once entered), total_price and currency, line_items, completed_at, and abandoned_checkout_url — the link that drops the shopper back into their checkout with everything still in it.

Subscriptions are declared in the app config. This is the shape we use:

[[webhooks.subscriptions]]
uri = "/webhooks/checkouts/update"
topics = [ "checkouts/create", "checkouts/update" ]

[[webhooks.subscriptions]]
uri = "/webhooks/orders/create"
topics = [ "orders/create" ]

The two things we learned the hard way

Webhooks arrive more than once, and out of order. The handler has to be idempotent — upsert by token, and prefer completed_at over arrival order when deciding whether a checkout is still open. A checkout can look abandoned in one event and completed in the next, delivered in the opposite sequence.

Answer fast, then do the work. Shopify expects a 2xx quickly; slow handlers get retried and, eventually, the subscription is dropped. Acknowledge first, process after.

The listing endpoints are for reconciliation, not timeliness

The GraphQL abandonedCheckouts query lists abandoned checkouts (the docs say it needs the read_orders scope). It's the right tool for backfilling on install and for reconciling your own records. It is not the timely signal: in our testing the listing lagged the webhook stream by hours while the webhooks were immediate.

The REST resource (GET /admin/api/{version}/checkouts.json) still works, but Shopify marked the REST Admin API as legacy as of October 1, 2024 and requires new public apps to use GraphQL from April 1, 2025. Start new work on GraphQL.

Protected customer data

Abandoned checkouts are full of personal data, and Shopify treats it as protected customer data. The shopper's name, address, phone and email are protected fields that have to be requested individually, with data-protection requirements attached (encryption, retention limits, a review before the App Store listing is approved). The practical consequence: if a feature only needs counts, totals or line items, don't request the fields — the approval is lighter and there's less to protect. An app that actually contacts the shopper can't avoid it; we store email addresses encrypted at rest for exactly this reason.

Two more things every app in this space needs: a retention rule of its own (Shopify deletes abandoned checkouts older than three months from the admin, so your copy shouldn't outlive that by much), and handlers for the three mandatory compliance topics — customers/data_request, customers/redact, shop/redact — which the App Store checks for.

Putting it together

Subscribe to checkouts/create, checkouts/update and orders/create.
Upsert the checkout by token on each event; mark it complete on completed_at or a matching order.
After your chosen delay, if it's still open, send the reminder using abandoned_checkout_url.
Backfill and reconcile with abandonedCheckouts; expire your records on your own schedule.

Step 3's delay is the interesting design decision — and the one thing Shopify leaves entirely to you. There's a related gotcha worth knowing before you gate anything on consent: Shopify only records the checkout marketing checkbox when the shopper proceeds to Pay now, so most abandoned checkouts carry no recorded consent. I wrote that one up here.

The full version of this map, with the merchant-facing side, lives on the Cartback blog. Cartback is a cart-recovery app for Shopify built on exactly these pieces.

TIL: Shopify only saves the checkout marketing checkbox when the shopper proceeds (Pay now, on one-page checkout)

Andras Palinkas — Mon, 21 Sep 2026 14:07:56 +0000

While building a cart-recovery app for Shopify, I hit a bug report I couldn't reproduce as a bug: a shopper ticks "Email me with news and offers" at checkout, abandons — and the abandoned checkout webhook arrives with buyer_accepts_marketing: false. Every time, in our tests.

It turned out not to be a bug. It's documented — just easy to miss, and it has real consequences for anyone building on the checkout APIs.

The documented behavior

Shopify's Help Center page on collecting customer contact information says consent is captured when the customer selects the marketing checkbox and proceeds — by selecting Pay now on one-page checkout, or Continue to shipping on three-page checkout.

And since one-page checkout became the default in 2023, most stores run the single-page layout — where the recording step is Pay now itself.

Put those together: an abandoned checkout is one where the purchase was never completed — in the common case, the shopper never pressed Pay now. So on a one-page store, an abandoned checkout from a first-time shopper will essentially never carry recorded consent, no matter what the checkbox showed on screen.

What I saw in testing

On a development store (July 2026), with a fresh email address:

checkouts/create fired within seconds of typing the email — with buyer_accepts_marketing: false and no customer object at all
ticking the checkbox afterwards produced no consent change in any subsequent checkouts/update
the REST /admin/checkouts.json listing lagged the webhooks by hours; the webhook stream was the timely signal (and Shopify has marked the REST Admin API as legacy since October 2024 — the GraphQL abandonedCheckouts query is the current read path)

Shopify's Abandoned Checkouts docs define the resource as: "A checkout is considered abandoned after the customer has added contact information, but before the customer has completed their purchase." Nothing about consent timing — which is what makes this easy to trip over.

Why it matters

Shopify's own abandoned checkout automation sends to subscribed customers only by default — one reason merchants often wonder why so few automatic recovery emails go out. The email's To: field can be switched to All customers, but that's a technical setting, not a legal green light: whether a recovery email to a non-subscribed shopper needs prior consent depends on jurisdiction (the EU is stricter than the US, for example).
If your app gates recovery emails on recorded consent, expect to skip most abandoned checkouts from new shoppers — not because shoppers didn't tick the box, but because Shopify never persisted it.
Returning customers who subscribed during an earlier completed purchase do carry consent, so their checkouts behave "normally" — which makes the behavior look intermittent if you don't know the rule.

Practical takeaways for builders

Read consent from the customer-level email_marketing_consent as well as the checkout's buyer_accepts_marketing — returning subscribers show up there. (The checkout webhook includes a customer object only when Shopify recognizes the shopper.)
Don't treat a false flag as "shopper declined" — on one-page checkout it mostly means "shopper never reached the recording step".
If your product's behavior depends on this (ours did), make the policy an explicit merchant setting rather than a silent gate.

I'm building Cartback, a cart-recovery app for Shopify — this is one of a few documented-but-easy-to-miss behaviors we've written up on the blog.