Global IDs in Shopify APIs

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.

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:

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:

The following table provides some common examples of global IDs that are associated with different GraphQL objects. For example purposes, each global ID is referenced as 123.

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:

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:

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:

Shopify's REST Admin API contains simple IDs, which differ from global IDs. A simple ID is a unique series of numbers that identifies a REST resource:

For example, the REST Admin API's DiscountCode resource includes an id property that has a simple ID as a value:

Simple IDs also exist for properties that have descriptive names appended by id. For example, the REST Admin API's GiftCard resource includes the following properties that each have a simple ID as a value:

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: