Migrate Private Metafields
Before access controls and ownership for metafields, the only way developers could create metafields that were private to their app was through private metafields. However, they have the following limitations:
- Only accessible from the Admin GraphQL API
- Limitation of 10 private metafields per resource
- Do not support metafield definitions
To use private metafields in our Admin GraphQL API, you would use the following mutations to write:
Starting with the 2023-01 API release, developers now have more options for storing their data privately.
App-owned Metafields
Anchor link to section titled "App-owned 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](https://shopify.dev/docs/api/admin-graphql/2023-01/mutations/metafieldsSet) mutation. As a result, when reading this metafield back the namespace will look like:
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.
Metafield Access Controls
Anchor link to section titled "Metafield Access Controls"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:
| Access Setting | Description |
|---|---|
| PRIVATE | Only the app that owns a metaobject of this type can read and write to it. |
| MERCHANT_READ | Apps that act on behalf of the app user (such as the admin) can read metaobjects of this type. Only the owning app can write to metaobjects of this type. |
| MERCHANT_READ_WRITE | Both the owning app and apps that act on behalf of the appuser (such as the admin) can read or write to metaobjects of this type. No other applications can read or write metaobjects. |
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.