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. ## Who 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. ## Requirements - Your app can make [authenticated requests](/docs/api/admin-graphql#authentication) 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. ## Limitations - ID metafield types are automatically configured to have unique values. - [Look up by custom ID](#step-4-look-up-the-resource-by-the-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](#step-5-mutate-a-resource-with-a-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. ## Step 1: Create an id metafield definition You can create an ID metafield definition using the GraphQL Admin API's [`createMetafieldDefinition`](#create-an-id-metafield-using-createmetafielddefinition) mutation ### Create an `id` metafield using CreateMetafieldDefinition The following example creates a pinned `id` metafield definition for the product owner type:

## Step 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.

## Step 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.

## Step 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`](/docs/api/admin-graphql/latest/queries/productByIdentifier) query. - If you've created a customer metafield definition, then use the [`customerByIdentifier`](/docs/api/admin-graphql/latest/queries/customerByIdentifier) query. - If you've created an order metafield definition, then use the [`orderByIdentifier`](/docs/api/admin-graphql/latest/queries/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:

## Step 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: