About metafields

Shopify includes built-in data models like products, customers, and orders. Metafields extend these models by letting you add custom data to any Shopify resource.

You can use metafields to add warranty information to products, track customer lifetime value, store fulfillment notes on orders, link related products, trigger Shopify Flow automations, or power backend processes. This flexibility lets you extend Shopify's data model for specialized features and business logic.

Want to skip ahead? Choose a path based on what you're building:

• Building an app: Use app-owned metafields with TOML configuration.
• Extending existing store data: Use merchant-owned metafields with GraphQL.

Anchor to What are metafields?What are metafields?

Metafields are key-value pairs with the following components:

• Identifier: A combination of namespace and key (for example, custom.warranty_info). Namespaces are logical containers that not only provide organization and prevent naming conflicts, they establish ownership.
• Value: The data being stored.
• Type: Defines the kind of value (such as text, number, date, or reference) and how the value is interpreted. See available types.

Anchor to Metafield definitionsMetafield definitions

Before creating a metafield, you will create a metafield definition. Metafield definitions establish data schemas that enable type validation, Shopify admin integration, query filtering, access control, and performance optimization.

Anchor to Metafield ownershipMetafield ownership

Ownership determines access and control. When creating metafields, you choose between two ownership models:

Additional ownership types:

• Shopify-reserved: Metafields with Shopify-controlled namespaces and structures, including those typically prefixed with reserved namespace shopify-- and standard definitions. Shopify controls the structure, but the metafields are typically merchant-owned.
• App-data: A special type of app-owned metafield tied to your app installation (not to products, customers, or orders) and completely hidden from the Shopify admin. See App-data metafields for details.

Anchor to App-owned metafieldsApp-owned metafields

App-owned metafields are custom data entries controlled by your app. Your app manages both the structure and values, which are view only in the Shopify admin (by default).

App-ownership is defined using the app reserved namespace.

Anchor to ExampleExample

You want to track internal SKU codes for products. Because your app manages inventory tracking, you create an app-owned metafield.

Anchor to Step 1: Create the metafield definitionStep 1: Create the metafield definition

Create the metafield definition using your app's shopify.app.toml file. The following creates the definition with app-owned namespace app and key internal_sku:

Deploy it with your app:

Anchor to Step 2: Create the metafieldStep 2: Create the metafield

After you create the metafield definition, add the metafield (value) using the GraphQL Admin API. Use the same namespace, key, and type from the definition:

Anchor to Merchant-owned metafieldsMerchant-owned metafields

Merchant-owned metafields are custom data entries that merchants and all installed apps can modify. Both the structure and values are editable, making them ideal for shared data across multiple apps.

Create merchant-owned metafields using any non-reserved namespace (such as custom, specs, or inventory).

Anchor to ExampleExample

You want to add warranty information to products. Because this type of field should be managed in the Shopify admin, you use a merchant-owned metafield.

Anchor to Step 1: Create the metafield definitionStep 1: Create the metafield definition

First, create the metafield definition using the GraphQL Admin API. The following example doesn't use namespace $app, so the definition will be merchant-owned:

Anchor to Step 2: Create the metafieldStep 2: Create the metafield

After you create the metafield definition, add the metafield (value). Use the same namespace, key, and type from the definition:

Anchor to App-data metafieldsApp-data metafields

App-data metafields are tied to a specific app installation and are completely hidden from the Shopify admin. They're stored on the AppInstallation resource and can only be accessed by the owning app via GraphQL or through the app object in Liquid. They can't be created using shopify.app.toml.

Unlike app-owned metafields on shared resources, the $app reserved namespace isn't required because the AppInstallation owner provides isolation — only your app can access its own installation's metafields.

Anchor to ExampleExample

You want to store a feature tier configuration for each app installation. Because this data should be completely hidden from merchants and specific to each installation, you use app-data metafields.

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

Get the app installation ID using the currentAppInstallation query:

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

Create the app-data metafield using the metafieldsSet mutation:

Anchor to PermissionsPermissions

Configure who can read and write your metafields using the access settings on your definition.

Anchor to Shopify admin permissionsShopify admin permissions

admin controls permissions for both the Shopify admin and the GraphQL Admin API.

For app-owned metafields:

# Merchants can view but not edit (default)
access.admin = "merchant_read"

# Merchants can view and edit
access.admin = "merchant_read_write"

access: {
  admin: MERCHANT_READ  # view only (default)
}

access: {
  admin: MERCHANT_READ_WRITE  # view and edit
}

For merchant-owned metafields:

• Always full access - readable and writable by merchants and all apps with appropriate scopes. No configuration needed.

Anchor to Storefront permissionsStorefront permissions

storefront controls permissions for the Storefront API (used by headless and custom storefronts). This setting doesn't affect Liquid templates - metafields are always accessible in Liquid regardless of this setting.

Available settings:

# Hidden from Storefront API (default)
access.storefront = "none"

# Accessible in Storefront API  
access.storefront = "public_read"

access: {
  storefront: NONE  # hidden (default)
}

access: {
  storefront: PUBLIC_READ  # accessible
}

Anchor to Customer accounts permissionsCustomer accounts permissions

customer_accounts controls permissions for the Customer Accounts API.

Available settings:

# Hidden from Customer Accounts API (default)
access.customer_account = "none"

# Readable in Customer Accounts API
access.customer_account = "read"

# Readable and writable in Customer Accounts API
access.customer_account = "read_write"

access: {
  customerAccount: NONE  # hidden (default)
}

access: {
  customerAccount: READ  # readable
}

access: {
  customerAccount: READ_WRITE  # readable and writable
}

Anchor to Next stepsNext steps

• Learn how to work with metafield definitions.
• Learn how to work with metafield values.
• Learn how to use metafields to query resources.
• Learn how to enable filtering and other advanced features.