Migrate private metafields

Regular metafields are “app-owned” if the metafield’s namespace contains your app's reserved namespace. An app reserved namespace is a metafield namespace that's prefixed with your app’s API client ID. This looks like:

app-{your-app-id}--{some-namespace}

Instead of requiring knowledge of your API client ID in the request, your app can use the $app: shorthand in front of the desired namespace to add the prefix. For example, if your app wanted to declare a private metafield with the namespace client_name, you would pass in $app:client_name as the namespace when creating the metafield through the metafieldsSet mutation. As a result, when reading this metafield back, the namespace looks like the following example:

app-12345–client_name

A metafield that uses a reserved prefix will be private by default and not accessible to anyone but your app. However, you may want to specify some granularity to how accessible your metafield can be.

As of the 2023-01 API version, private metafields have been migrated to app-owned metafields with reserved namespaces. The following sections show you how to migrate your app to use the new metafields system.

In API version 2023-10 and lower, you could retrieve private metafields using the following queries:

As of the 2023-01 API version, you can use the following queries (for types implementing hasMetafields) with the $app: shorthand followed by your private metafield's namespace:

Both the metafield and metafields query above under product (or other resource implementing hasMetafields) will filter through your app-owned metafields matching the specified namespace: app-{your-app-id}--some_namespace for that product. The metafields query returns a paginated list of metafields whilst metafield returns a single metafield by also matching against a specified key.

As of the unstable API version, you can also use the metafields query with the $app: shorthand:

In API version 2023-10 and lower, you could create or update private metafields using the following mutation:

As of the 2023-01 API version, you can create or update an app-owned metafield with the metafieldsSet mutation and use the $app: shorthand followed by the desired namespace:

The metafieldsSet mutation takes an array of MetafieldsSetInput allowing you to create or update more than one app-owned metafield.

In API version 2023-10 and lower, you could delete private metafields using the following mutation:

As of the 2023-01 API version, you can use the id of your app-owned metafield to delete it using the metafieldDelete mutation:

If you previously had webhook subscriptions that returned the associated private metafields by namespace, then you can create new ones to return your app-owned metafields.

The following mutations are available to create webhook subscriptions:

• webhookSubscriptionCreate
• eventBridgeWebhookSubscriptionCreate
• pubSubWebhookSubscriptionCreate

In API version 2023-10 and lower, you could use the privateMetafieldNamespaces to filter by the private metafield namespace:

As of the 2023-01 API version, you can use the $app: shorthand followed by the namespace under metafieldNamespaces:

Since the 2021-10 API release, developers can define the metafields they want to use on a resource by creating a metafield definition. Metafield definitions provide developers with validation options on the data stored, the ability to reserve a namespace/key on the resource it’s defined on and metadata about the field such as name and description.

In the 2023-01 API release, metafield definitions now offer a new input field named access that allows developers to specify the granularity in which the data stored in the metafield is exposed. There are three levels of access:

By default, metafields defined by apps under namespaces that they own (meaning that the namespace contains the app's reserved prefix) will be private to the app. Similar to app-data metafields, after a metafield is defined, reading and writing to it is the same as other regular metafields.