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 Files

Download a sample spreadsheet to see the structure for importing metafield definitions:

Metafield Definitions Sample - Create product and variant metafield definitions including single line text, boolean, and list of numbers types

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 (will skip if definition doesn't exist)
NEW: Create definition only (will skip 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
TRANSFER: Metafields for inventory transfers

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.

Capability: Smart Collection Condition

Description	Example Value
If the metafield can be used as a smart collection condition	`TRUE`

TRUE: Smart collections can use this metafield in their conditions
FALSE: Smart collections cannot use this metafield in their conditions

Only product and product variant definitions can turn this on. When you update an existing definition and leave this cell blank, or leave the column out of your file, the current setting is kept. Shopify does not let you turn this off while a smart collection still uses the metafield in one of its conditions. If Shopify rejects the value you get warning MDEF010 and the rest of the definition is still saved.

Capability: Admin Filterable

Description	Example Value
If the metafield can be used to filter lists in the admin	`TRUE`

TRUE: The metafield is available as a filter in the Shopify admin
FALSE: The metafield is not available as a filter

Shopify only supports admin filtering for some owner types and metafield types. Leave the cell blank to keep the current setting. Shopify may take a few minutes to finish indexing after you turn this on.

Capability: Unique Values

Description	Example Value
If every metafield under this definition must be unique	`FALSE`

TRUE: Two objects cannot store the same value for this metafield
FALSE: Duplicate values are allowed

Shopify only supports unique values for some metafield types, and it cannot be turned on while existing metafields already share a value. Leave the cell blank to keep the current setting.

Capability: Analytics Queryable

Description	Example Value
If the metafield can be used in Shopify analytics	`FALSE`

TRUE: The metafield can be queried in Shopify analytics and reports
FALSE: The metafield is not available in analytics

Leave the cell blank to keep the current setting.

Capability: Cart To Order Copyable

Description	Example Value
If cart metafield values are copied to the order at checkout	`FALSE`

TRUE: When an order is created, the value of this cart metafield is copied to the matching order metafield
FALSE: Cart metafield values are not copied to orders

This only applies to cart definitions. Leave the cell blank to keep the current setting.

Access: Admin

Description	Example Value
Who can read and write the metafield in the admin	`MERCHANT_READ_WRITE`

MERCHANT_READ: The merchant has read-only access and other apps have no access
MERCHANT_READ_WRITE: The merchant has read and write access and other apps have no access
PUBLIC_READ: The merchant and other apps have read-only access - Export only
PUBLIC_READ_WRITE: The merchant and other apps have read and write access - Export only
PRIVATE: The merchant and other apps have no access - Export only

Shopify only lets an app restrict admin access on the app's own namespaces, so this column is mainly useful for exports. PUBLIC_READ, PUBLIC_READ_WRITE, and PRIVATE are ignored on import so that you can re-import an exported file. If you set MERCHANT_READ or MERCHANT_READ_WRITE on a namespace such as custom, Shopify rejects it and you get warning MDEF011. Leave the cell blank to keep the current setting.

Access: Storefront

Description	Example Value
Whether the Storefront API can read the metafield	`PUBLIC_READ`

PUBLIC_READ: The metafield can be read through the Storefront API
NONE: The metafield is not exposed to the Storefront API

Leave the cell blank to keep the current setting. Any other value fails the row with error MDEF009.

Access: Customer Account

Description	Example Value
What the Customer Account API can do with the metafield	`NONE`

READ_WRITE: Customer accounts can read and write the metafield
READ: Customer accounts can read the metafield
NONE: The metafield is not exposed to the Customer Account API

Leave the cell blank to keep the current setting. Any other value fails the row with error MDEF009.

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.

Validation: Value

Description	Example Value
Value used for the validation	`100`

The specific value or constraint for the validation rule. For example, if the validation name is max, this would be the maximum allowed value.

Metaobject Definition References

For metafield definitions with metaobject_reference, list.metaobject_reference, mixed_reference, or list.mixed_reference types, validations specify which metaobject definitions are allowed. These validations use:

metaobject_definition_id: References a single metaobject definition (for metaobject_reference and list.metaobject_reference types)
metaobject_definition_ids: References multiple metaobject definitions (for mixed_reference and list.mixed_reference types)

When exporting, Altera converts these from Shopify GIDs to type handles for cross-store compatibility:

Format	Example Value
Single definition	`features`
Multiple definitions	`camera_specs, speaker_specs, brand`

When importing, Altera accepts both formats:

Type handles (recommended): features or camera_specs, speaker_specs
GIDs (legacy): gid://shopify/MetaobjectDefinition/123456

This enables you to export metafield definitions from one store and import them into another store, as long as the referenced metaobject definitions exist in the destination store. If a referenced definition doesn't exist, you'll receive error MOBD006.

Metafield Definition Fields