Global IDs in Shopify APIs

Shopify's GraphQL APIs use global IDs to refer to objects, including the GraphQL Admin API, the Storefront API, and the Customer Account API. A global ID is an application-wide uniform resource identifier (URI) that uniquely identifies an object. You can use a global ID to retrieve a specific Shopify object of any type.

The REST Admin API uses numeric IDs instead. To move between the two, refer to finding equivalent IDs between REST and GraphQL.

Anchor to How it worksHow it works

To enable GraphQL clients to neatly handle caching and data refetching, GraphQL servers expose object identifiers in a standardized way using the Relay specification.

Relay asks for a compliant server to expose a standard mechanism for fetching any object given an ID. These objects are referred as nodes and they implement the Node interface. Shopify's GraphQL APIs provide a versionable implementation of this interface.

Anchor to Global ID structureGlobal ID structure

Shopify uses GlobalID to encode global IDs. By default, when implementing a Node interface, a type's id field constructs a global ID with the following structure:

For example, a Product object with the ID 123 would resolve to the following global ID:

Anchor to Parameterized global IDsParameterized global IDs

Some objects are more complex and have global IDs that contain parameters. A global ID with parameters has the following structure:

For example, the InventoryLevel object is associated with the InventoryItem object. If the InventoryLevel object's ID is 123 and the InventoryItem object's ID is 456, then the global ID would resolve to the following structure:

Anchor to Global ID examplesGlobal ID examples

Because every type follows the same structure, you can construct a global ID for any object from its type name. Type names are listed in each API's reference, for example the GraphQL Admin API reference. For example purposes, each global ID below is referenced as 123.

The last row is a parameterized global ID: a child object that needs its parent's ID to be uniquely identified. Check the type's id field in the reference when you're not sure whether a parameter is required.

Anchor to Querying global IDsQuerying global IDs

A node is an object that has a global ID and is of a type that's defined by the schema. Connections retrieve a list of nodes. For example, the products connection finds all the Product type nodes connected to the query root.

The following example shows how to use the GraphQL Admin API to query the global IDs of the first 5 products in your store:

Anchor to Retrieving global IDs through the UIRetrieving global IDs through the UI

Some global IDs can be quickly retrieved through the user interface (UI). For example, you can find a product's global ID from your Shopify admin by clicking Products and clicking a specific product. The URL of the page contains the product's global ID:

Anchor to Using global IDs in mutationsUsing global IDs in mutations

Many mutations in Shopify's GraphQL APIs require an id input field. The value of the id field needs to be constructed as a global ID.

The following example shows how to use an id input field to update a product's status:

Anchor to Finding equivalent IDs between REST and GraphQLFinding equivalent IDs between REST and GraphQL

Most REST Admin API resources include an admin_graphql_api_id property, which provides a global ID for the equivalent object in the GraphQL Admin API. For example, the following two properties on the Customer resource are equivalent:

Similarly, most GraphQL Admin API objects include a legacyResourceId field, which provides a simple ID for the equivalent resource in the REST Admin API. For example, the following two fields on the Product object are equivalent: