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: