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

