Skip to content

Shopify Dude Fix

Shopify Order Webhook checkout_id Is Missing in 2026-04: Migrate to checkout_token

Order and checkout webhooks changed in 2026-04. Replace checkout_id and checkout id joins with checkout_token and token, then test replay and idempotency.

Quick answer: In Shopify API version 2026-04, affected orders/* webhook payloads no longer include checkout_id; use checkout_token. checkouts/create and checkouts/update no longer include id; use token. Do not treat the two tokens as numeric checkout IDs.
On this page

Why the integration suddenly stops matching orders

Older integrations often store a numeric checkout ID from checkouts/update, then use orders/create.checkout_id to reconcile abandoned checkout activity with completed orders. That join becomes empty after a version change. Shopify announced the removal on March 6, 2026 for the 2026-04 webhook schema. This is a payload contract change, not evidence that checkout attribution disappeared.

Change the data model before the webhook handler

Introduce a nullable string checkout_token on both checkout-event and order-event records. Keep any old numeric ID as a historical field during migration. Make the reconciliation job prefer the token when both sides provide it; don’t coerce it into an integer. Audit your consumers for checkout_id and checkout webhook id, including ETL jobs, event queues, analytics transforms, and CRM syncs.

Concrete handler pattern

function checkoutKey(topic, payload) {
  if (topic.startsWith('checkouts/')) {
    return payload.token ?? null;
  }
  if (topic.startsWith('orders/')) {
    return payload.checkout_token ?? null;
  }
  return null;
}
// Persist the token as a string; reject an absent key for
// checkout reconciliation, but still process the order itself.

Keep webhook deduplication separate: a checkout token identifies a checkout, not an individual delivery attempt. Use Shopify’s webhook delivery identifiers and your own processing ledger for idempotency. Preserve the raw payload during the rollout so you can diagnose discrepancies.

Common misunderstanding: Renaming checkout_id to checkout_token in one SQL query is enough. It is not if upstream schemas, integer columns, message serialization, or downstream jobs still expect the old value. Also, an order without a checkout token should not be discarded.

How to test this

  1. Pin a test webhook subscription to API version 2026-04 or later and record its version.
  2. Complete a test checkout and inspect the checkout and order webhook JSON.
  3. Confirm checkout events contain token and affected order events contain checkout_token.
  4. Verify the same token joins the two records; compare with historical rows before cutover.
  5. Replay the same webhook twice and confirm the processor does not duplicate work.
  6. Test a manually created order with no checkout token; it must still enter the order pipeline.
  7. Monitor unmatched checkout events and failed jobs after deployment.