About metaobjects

Metaobjects enable you to define custom data structures with multiple related fields. While metafields add individual custom fields to existing Shopify resources, metaobjects let you create entirely new types of structured data that can be referenced and reused across your store.

You can use metaobjects to, for example, create product size charts with multiple measurements, author profiles with biographical information and contact details, ingredient lists with nutritional data, or warranty information with terms and conditions. This flexibility allows you to model complex data relationships and create rich content structures.

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

• Building an app: Use app-owned metaobjects with TOML configuration.
• Extending store content: Use merchant-owned metaobjects with GraphQL.

Anchor to What is a metaobject?What is a metaobject?

A metaobject is an instance of structured data with multiple related field values. Unlike metafields that attach single values to existing resources, metaobjects are standalone entities that can be referenced from multiple resources.

Each metaobject contains:

• ID: Unique identifier assigned by Shopify.
• Handle: URL-friendly identifier (auto-generated from display name, or custom).
• Display name: Human-readable name (auto-generated from a specified field).
• Field values: Data defined by its metaobject definition.
• Capability states: Optional states like published/unpublished (if enabled).

For example, an author metaobject might include a name, biography, email, and profile photo - all stored together as a single reusable entity.

Anchor to Metaobject definitionsMetaobject definitions

Before creating metaobjects, you create a metaobject definition. Metaobject definitions are schemas that specify the structure, fields, and rules for a metaobject type.

A definition establishes:

• Type identifier: The category name for your custom object (for example, $app:author or size_chart). This identifies what kind of metaobject entries you'll create.
• Fields: What data the metaobject stores (name, key, data type, validation rules).
• Access permissions: Who can edit and where entries can be accessed (Shopify admin, storefront).
• Capabilities: Optional features like publishable or renderable.
• Display configuration: How entries appear (field order, display name field).

The relationship is: one definition can have many metaobject instances (entries). For example, one "author" definition can have metaobjects for Jane Smith, John Doe, and other individual authors.

Anchor to Metaobject ownershipMetaobject ownership

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

Additional ownership types:

• Shopify-reserved: Standard metaobject definitions for platform features. Shopify controls the structure, but merchants typically own and manage the entries. Developers don't create these but can enable standard definitions for certain use cases like product reviews.

Anchor to App-owned metaobjectsApp-owned metaobjects

App-owned metaobjects are custom data structures that are managed by your app. These metaobject entries are used for features requiring multiple related fields, such as configuration panels, content templates, or complex product attributes.

App-ownership is defined using the app reserved type prefix and can be created using your app's shopify.app.toml file.

Anchor to ExampleExample

You want to create author profiles with biographical information that can be referenced from blog posts. Because you want your app to own and control the structure, you create an app-owned metaobject.

Anchor to Step 1: Create a metaobject definitionStep 1: Create a metaobject definition

Create the metaobject definition using your app's shopify.app.toml file. The following creates the definition with app-owned prefix app and type identifier author:

Deploy it with your app:

Anchor to Step 2: Create the metaobjectsStep 2: Create the metaobjects

After you create the metaobject definition, create metaobjects (entries) using the GraphQL Admin API. Use the same type identifier and field keys as your definition:

Anchor to Merchant-owned metaobjectsMerchant-owned metaobjects

Merchant-owned metaobjects are custom data structures that can be managed in the Shopify admin or through any installed app. These metaobject entries are ideal for content that should be accessible and editable through the admin interface or multiple apps.

Merchant-ownership is defined by using any non-reserved type and can be created using the GraphQL Admin API.

Anchor to ExampleExample

You want to add size chart information to products. Because this type of structured data should be managed in the Shopify admin and accessible to all apps, you use a merchant-owned metaobject.

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

Create the metaobject definition using GraphQL. The following creates the definition with type identifier size_chart (no prefix makes it merchant-owned):

Anchor to Step 2: Create the metaobjectsStep 2: Create the metaobjects

Create metaobjects (entries) for specific size charts:

Anchor to PermissionsPermissions

Configure who can read and write your metaobjects 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 metaobjects:

# 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 metaobjects:

• 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).

Available settings:

# Not accessible on storefront (default)
access.storefront = "none"

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

access: {
  storefront: NONE  # not accessible (default)
}

access: {
  storefront: PUBLIC_READ  # accessible via Storefront API
}

Anchor to Use in Shopify FunctionsUse in Shopify Functions

You can query app-owned metaobjects directly in function input queries. This works across all function types, including discounts, cart transforms, delivery customization, and fulfillment constraints.

The type must use the $app reserved prefix (for example, $app:pricing-config). Merchant-owned types don't work in function input queries.

Each metaobject root costs 1 complexity point, and each field(key:) call costs 3 points. A query with one metaobject and three fields costs 10 points total. The input query budget is 30 points. For the full cost breakdown, refer to input query limits.

Anchor to Next stepsNext steps

• Learn how to model your data structure.
• Learn how to work with metaobject definitions.
• Learn how to work with metaobject entries.
• Learn how to use metaobjects to query entries.
• Learn how to enable advanced features.
• Learn how to use app-owned metaobjects in function input queries.