Shopify GID Decoder.

Why Shopify moved from numeric IDs to GIDs

REST gave every resource a plain 64-bit integer. 1234567890 is a fine primary key and a terrible identifier: on its own it does not tell you whether it points at a product, an order or a customer, so the type has to travel next to it in a separate field, a separate column, or somebody's head. GraphQL cannot work that way. A single field can return several types, and a client-side cache needs one string it can use as a key.

So Shopify adopted Relay's global object identification pattern: gid://shopify/Product/1234567890. Scheme, namespace, type, legacy ID. One string that is unique across the whole API, carries its own type, and can be handed to node(id:) or nodes(ids: [...]) to fetch anything without knowing up front what it is. That is also why Apollo and urql can normalise a Shopify response without configuration — the id field is already globally unique.

When you still need the legacy numeric ID

GIDs did not replace the numeric IDs; they wrap them. The number is still what half of the platform speaks, and you will keep converting between the two for as long as you work on Shopify.

The places it bites: webhook payloads are REST-shaped, so id is the number — but Shopify also ships admin_graphql_api_id in the same object, so reach for that instead of concatenating. Liquid gives you product.id as an integer. Admin URLs are all numeric, which is why this tool accepts one and pulls the ID out. CSV and report exports that include an Id column give you the number. And any ERP, 3PL or legacy database you integrated with in 2019 has a column full of integers. Going the other way, the GraphQL field you want is legacyResourceId — it returns the numeric ID as a string, and it means you never parse a GID yourself.

The base64 era, and why encoding assumptions rot

For years the Storefront API base64-encoded every ID it returned, so gid://shopify/Product/1234567890 came back as Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzEyMzQ1Njc4OTA=. The Admin API never did. Shopify dropped the encoding in API version 2022-04, and both forms are still accepted as input — which is a friendly API and a nasty source of bugs.

The failure mode is comparison, not decoding. Two rows hold the same product, one written by an old storefront and one by a new webhook handler, and a === b is false. Deduplication silently doubles the catalogue. A cache keyed on the encoded string never hits. If you store IDs, normalise on write: decode base64 if it decodes to something starting with gid://, keep the plain form, and never assume the shape of what the next API version hands you. This tool decodes with atob plus TextDecoder in fatal mode, so a string that merely looks like base64 fails loudly instead of producing mojibake.

A GID is opaque — including the one this tool just built you

Shopify's position is that a GID is an opaque token: read it from a response, pass it back, do not manufacture it. The builder above ignores that on purpose, because when you are staring at a support ticket with a numeric order ID in it you need a GID in ten seconds, not a query. Shipping that pattern into production is a different matter.

Three concrete reasons it breaks. The type name has to be exactly right and exactly PascalCase — gid://shopify/product/1 is not a typo the API forgives, and MediaImage, ProductImage and Image are three different things. Some resources need query parameters as part of the identifier: an inventory level is the pair of a location and an inventory item, so its GID carries ?inventory_item_id=…. And some IDs are not numbers at all — a Storefront cart ID is an opaque token, so any code doing "gid://shopify/Cart/" + parseInt(x) is already broken. When a bulk migration really does force your hand, build the strings, then validate them through nodes(ids: [...]) and treat every null in the response as a mapping you got wrong.

What this page accepts

Parsing is a string split, not a regex guess: everything after gid:// is cut at the first ?, the path must be exactly three segments, and the query is read with URLSearchParams so repeated and empty values survive. Anything that fails names the reason — one slash instead of two, a stray fragment, a space in the middle, four segments because a URL got pasted in. Inputs that are not GIDs are tried in order: a Shopify admin URL (the last /segment/12345 pair wins, so /products/1/variants/2 resolves to the variant), a bare integer, then base64. The notes panel flags the things that parse but still look wrong — a non-shopify namespace, a lowercase type, a leading zero, an InventoryLevel missing its parameter. All of it runs locally; the page works with the network unplugged.

Questions people ask

Related

• ▸ Blog Agentic commerce on Shopify Where GIDs show up when an agent is the thing calling the Admin API instead of a person.
• ▸ Blog Shopify Liquid vs headless Liquid hands you numeric IDs, the Storefront API hands you GIDs. Picking a stack means picking which one you live with.
• ▸ Blog Shopify UCP quick start Getting a catalog and its identifiers out of Shopify and into something a model can use.
• ▸ Tool Shopify HMAC Verifier The other half of webhook handling — check the signature before you trust the IDs inside the payload.

Keep reading

• ▸ Tool

  Shopify Webhook HMAC Verifier

  The other Shopify thing that fails silently: webhook signature verification.

• ▸ Post

  /blog/agentic-commerce-shopify/

  Why structured, machine-readable product IDs suddenly matter a lot more.

• ▸ Post

  /blog/shopify-liquid-vs-headless/

  Which ID format you get depends on which storefront stack you picked.

• ▸ Tool

  Base64 Encoder / Decoder

  Older Shopify APIs hand back base64-wrapped GIDs. Here's the decoder.