Metafield definitions are templates that standardize how metafields work across different objects in your Shopify store. They define the structure, validation rules, and display settings for metafields, ensuring consistency when the same metafield is used on products, customers, orders, and other resources.

When importing data with multiple rows per definition (such as definitions with multiple validation rules), rows are grouped together to form complete metafield definition objects using the ID or namespace/key combination.

Sample File

Download a sample spreadsheet to see the structure for importing metafield definition data.

General

ID

Description	Example Value
Unique metafield definition identifier	`gid://shopify/MetafieldDefinition/123456789`

Shopify's unique identifier for the metafield definition. When creating new definitions, this field can be left empty and Shopify will generate a unique ID automatically.

Namespace

Description	Example Value
The metafield namespace of the definition - Create only	`custom`

The namespace groups related metafields together. This field can only be set when creating new definitions and cannot be changed afterward. Common namespaces include custom, global, or app-specific namespaces.

Key

Description	Example Value
The metafield key of the definition - Create only	`review_count`

The key identifies the specific metafield within its namespace. Combined with the namespace, this creates a unique identifier. This field can only be set when creating new definitions and cannot be changed afterward.

Command

Description	Example Value
Import action	`MERGE`

MERGE: Update existing definition or create if not found
DELETE: Remove the metafield definition from your store
NEW: Create definition only (fails if definition exists)
REPLACE: Delete existing definition and create new one
IGNORE: Skip this definition row during import

Name

Description	Example Value
Metafield definition name	`Review Count`

The human-readable name for the metafield definition, displayed in the Shopify admin interface.

Owner Type

Description	Example Value
What type of object the metafield definition belongs to - Create only	`PRODUCT`

PRODUCT: Metafields for products
PRODUCTVARIANT: Metafields for product variants
COLLECTION: Metafields for collections
CUSTOMER: Metafields for customers
ORDER: Metafields for orders
DRAFTORDER: Metafields for draft orders
COMPANY: Metafields for companies
COMPANY_LOCATION: Metafields for company locations
LOCATION: Metafields for locations
PAGE: Metafields for pages
BLOG: Metafields for blogs
POST: Metafields for blog posts
MARKET: Metafields for markets

This field can only be set when creating new definitions and cannot be changed afterward.

Description

Description	Example Value
Metafield definition description	`This stores the total reviews for the product`

Detailed description explaining the purpose and usage of this metafield definition.

Pinned: Is Pinned

Description	Example Value
If the metafield definition is pinned in the Shopify admin	`TRUE`

TRUE: The metafield definition is pinned and appears prominently in the Shopify admin
FALSE: The metafield definition is not pinned

Pinned metafields are displayed more prominently in the admin interface for easier access.

Pinned: Position

Description	Example Value
The definition's order in the pinned list - Export only	`1`

The position of this definition in the list of pinned metafields. Lower numbers appear first. This field is export-only and cannot be imported.

Type: Category

Description	Example Value
The category of the definition's field type - Export only	`TEXT`

The high-level category that this metafield type belongs to (e.g., TEXT, NUMBER, FILE). This field is export-only and cannot be imported.

Type: Name

Description	Example Value
The type of field for the metafield definition - Create only	`single_line_text_field`

The specific field type that determines how the metafield value is stored and displayed. This field can only be set when creating new definitions and cannot be changed afterward.

Top Row

Description	Example Value
Whether this is the first row for this definition	`TRUE`

TRUE: This is the first row for this metafield definition object
FALSE: This is a continuation row for the same definition

Used internally for grouping multiple rows together into a single metafield definition.

Row

Description	Example Value
Row number in the spreadsheet	`1`

Sequential number identifying the position of this row in the import spreadsheet.

Validation

Validation: Name

Description	Example Value
Name of the validation	`max`

The name of the validation rule to apply to this metafield definition. Common validation names include max, min, choices, and others depending on the field type.

Validation: Type

Description	Example Value
Data type of the validation - Export only	`number_integer`

The data type expected for the validation value. This field is export-only and cannot be imported as it's determined by the validation name and field type.