Working with custom IDs

You can create custom IDs when you need a reliable unique identifier to match resources across multiple shops and/or systems (e.g. ERPs, CRMs, PIMs). This guide shows you how to create and manage custom IDs using Metafields in the GraphQL Admin API.

Anchor to Who is this forWho is this for

Any developer who uses external systems (e.g., PIM, ERP) and wants to create a mapping of identifiers to manage data migration and synchronization with Shopify.

Anchor to RequirementsRequirements

• Your app can make authenticated requests to the GraphQL Admin API.
• You have access to the type of resource that you want to add the metafield on. For example, setting a metafield on a PRODUCT requires the same access as mutating a product.

Anchor to LimitationsLimitations

• ID metafield types are automatically configured to have unique values.

• Look up by custom ID is not available for all resource types. It is currently supported for:

  • Products
  • Product Variants
  • Collections
  • Customers
  • Orders
  • Locations

• Create or update by custom ID is not available for all reference types. It is currently supported for:

  • Products (with productSet)
  • Customers (with customerSet)
  Note

  Look up by custom ID is only available using the GraphQL Admin API.

Anchor to Step 1: Create an id metafield definitionStep 1: Create an id metafield definition

You can create an ID metafield definition using the GraphQL Admin API's createMetafieldDefinition mutation

Anchor to Create an ,[object Object], metafield using CreateMetafieldDefinitionCreate an id metafield using CreateMetafieldDefinition

The following example creates a pinned id metafield definition for the product owner type:

Anchor to Step 2: Add an ,[object Object], metafield to a new resourceStep 2: Add an id metafield to a new resource

Add a metafield to the corresponding resource type using the id type with the namespace and key for your definition. For example, add a metafield to a new product if you created a product metafield definition.

Anchor to Step 3 (Optional): Add an ,[object Object], metafield to an existing resourceStep 3 (Optional): Add an id metafield to an existing resource

Add a metafield to the corresponding resource type using the id type with the namespace and key from your definition. In the following example, add a metafield to an existing product if you've created a product metafield definition.

Anchor to Step 4: Look up the resource by the Custom IDStep 4: Look up the resource by the Custom ID

After you've added the Custom ID metafield to a resource, you can look up that resource by its custom ID. Here are some examples of available GraphQL Admin API queries:

• If you've created a product metafield definition, then use the productByIdentifier query.

• If you've created a customer metafield definition, then use the customerByIdentifier query.

• If you've created an order metafield definition, then use the orderByIdentifier query.

  Similar ByIdentifier queries are available for other supported resource types like collections and product variants.

  The following example looks up a product by the Custom ID:

Anchor to Step 5: Mutate a resource with a Custom IDStep 5: Mutate a resource with a Custom ID

You can also update or create some resources by referencing their Custom ID. This is available for products via the productSet mutation, and customers via customerSet. When the identifier argument for these mutations includes a custom ID, they will first look up a matching record. If one exists, the mutation will update it. Otherwise, the mutation will attempt to create a new record with the provided inputs.

The following example looks up a product using the Custom ID format from Step 4 and updates its title:

The following example demonstrates how productSet creates a new product when the Custom ID doesn't match existing products: