Skip to main content

Ownership

Metafields and metaobjects can be owned by merchants or apps. Merchant owned metafields and metaobjects are open to merchants and developers, which means there are no restrictions on who can read, write, or modify them. However, you can use reserved namespaces to gain control over your application's data.

Anchor to Reserved prefixesReserved prefixes

There is a reserved prefix your app can prepend to metafield namespaces and metaobject types to take ownership of them. Using a reserved namespace ensures that your app exclusively controls all structure, data, permissions, and optional features.

Tip

Learn more about permissions.

Anchor to Create metafield definitions with reserved namespacesCreate metafield definitions with reserved namespaces

To establish metafield definitions within a reserved namespace, prefix the namespace with $app. The API will automatically convert this to a fully qualified reserved namespace like app--{your-app-id}[--{optional-namespace}]:

  • app: Indicates that this is a reserved namespace for an app.
  • {your-app-id}: Your app's unique API client ID.
  • {optional-namespace}: An optional namespace of your choosing.

For example, if your app's API client ID is 123456, you can create both:

  • $app → app--123456
  • $app:influencer → app--123456--influencer
Note

All APIs default to using a reserved namespace $app.

Example:

The following example creates a product metafield definition under a reserved namespace:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
metafieldDefinitionCreate(definition: {
name: "Ingredients",
key: "ingredients",
description: "List of ingredients used in the product.",
type: "list.single_line_text_field",
ownerType: "PRODUCT"
}) {
createdDefinition {
name
namespace
key
}
}
}

JSON response

{
"metafieldDefinitionCreate": {
"createdDefinition": {
"name": "Ingredients",
"namespace": "app--123456",
"key": "ingredients"
}
}
}

Anchor to Create metaobject definitions with reserved typesCreate metaobject definitions with reserved types

Similar to metafields, you can create metaobject definitions owned by your app by using the reserved prefix syntax for the metaobject type.

The following example creates a product highlight metaobject definition under a reserved namespace, while overriding the default permissions to grant the merchant read and write access:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
metaobjectDefinitionCreate(definition: {
name: "Product Highlight",
type: "$app:product_highlight",
access: {
admin: MERCHANT_READ_WRITE,
storefront: PUBLIC_READ,
},
displayNameKey: "title",
fieldDefinitions: [
{
key: "title",
type: "single_line_text_field",
},
{
key: "description",
type: "multi_line_text_field",
},
{
key: "creative",
type: "file_reference",
},
]
}) {
metaobjectDefinition {
id
type
permissions
fieldDefinitions {
key
type
}
}
}
}

JSON response

{
"data": {
"metaobjectDefinitionCreate": {
"metaobjectDefinition": {
"id": "gid://Shopify/MetaobjectDefinition/1",
"type": "app--123456--product_highlight",
"permissions": {
"admin": "MERCHANT_READ_WRITE",
"storefront": "PUBLIC_READ"
},
"fieldDefinitions": [
{ "key": "title", "type": "single_line_text_field" },
{ "key": "description", "type": "multi_line_text_field" },
{ "key": "creative", "type": "file_reference" }
]
}
}
}
}

Anchor to App-data metafieldsApp-data metafields

An app-data metafield is a metafield that is tied to a particular app installation and can only be accessed by that app. App-data metafields can't be overwritten by other apps or by merchants, and can be accessed using GraphQL. You can access app-data metafields using the metafields property on the app object in Liquid.

Using app-data metafields, you can provide different levels of features to users depending on their app payment plan by using app-data metafields and conditional app blocks. You can also store a client ID or client secret in app-data metafields.

The following steps demonstrate how to create and manage app-data metafields, which are metafields that are tied to a specific app installation. You'll learn how to securely store app-specific data that can't be modified by other apps or merchants.

Anchor to RequirementsRequirements

Anchor to Step 1: Retrieve the app installation IDStep 1: Retrieve the app installation ID

First, use the currentAppInstallation query to retrieve the ID of the AppInstallation object associated with your app. In the next step, you'll use this ID to create a new app-data metafield.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query {
currentAppInstallation {
id
}
}

Response

{
"data": {
"currentAppInstallation": {
"id": "gid://shopify/AppInstallation/123456"
}
}
}

Anchor to Step 2: Create an app-data metafieldStep 2: Create an app-data metafield

To create an app-data metafield, use the metafieldSet mutation, setting ownerID to the app installation ID from the previous step:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation CreateAppDataMetafield($metafieldsSetInput: [MetafieldsSetInput!]!) {
metafieldsSet(metafields: $metafieldsSetInput) {
metafields {
id
namespace
key
}
userErrors {
field
message
}
}
}

Variables

{
"metafieldsSetInput": [
{
"namespace": "secret_keys",
"key": "api_key",
"type": "single_line_text_field",
"value": "aS1hbS1hLXNlY3JldC1hcGkta2V5Cg==",
"ownerId": "gid://shopify/AppInstallation/3"
}
]
}

After you've created a metafield, you can access its value using the metafield field on the AppInstallation object.

Anchor to Next stepsNext steps

Was this page helpful?