Sample File
This sample file shows the basic columns that you need to set in order to import metaobject definitions to Shopify.
Download sample Metaobject Definition Import File.
Notes
Shopify-Managed Definitions
Shopify manages certain metaobject definitions internally (type names starting with shopify--). These are included in exports by default and fall into two categories for import:
Product Category Definitions
Product category metaobject definitions like shopify--color-pattern, shopify--material, or shopify--style are part of Shopify's Product Taxonomy. While these cannot be created or modified, Altera can enable them on your store during import. This is useful when migrating products between stores that use category attributes.
When you import a product category metaobject definition, Altera will enable it if it's not already enabled, or skip it if it already exists. This also happens automatically when importing products with category metafields.
Other Shopify-Managed Definitions (cannot be imported)
Other Shopify-managed definitions cannot be created, updated, or modified through the API. Attempting to import them will result in error MOBD005.
What you can import:
Custom metaobject definitions (those not managed by Shopify)
Product category metaobject definitions (will be enabled, not created)
General
ID
Description | Example Value |
Unique definition identifier |
|
If present, the ID will be used to find an existing metaobject definition on the store. When importing, the ID will be used to see if the definition already exists. If there's no ID match the app will attempt to find an existing definition using the Type.
Type
Description | Example Value |
The metaobject type identifier (Create-only) |
|
The unique type identifier for this metaobject definition. This is used to identify the type of metaobjects created from this definition. This field can only be set during creation and cannot be changed later.
Command
Description | Example Value |
Action to perform: MERGE, DELETE, NEW |
|
MERGE: Update existing definition or create if not found
DELETE: Remove the definition from the store (only if no metaobjects reference it)
NEW: Create a new definition (will skip if definition already exists)
Name
Description | Example Value |
Display name for the metaobject definition |
|
The human-readable name for this metaobject definition that appears in the Shopify admin.
Description
Description | Example Value |
Description of the metaobject definition |
|
A description explaining what this metaobject definition is used for.
Metaobject Count
Description | Example Value |
Number of metaobjects using this definition (Export-only) |
|
The total number of metaobjects that have been created using this definition. This field is export-only and cannot be imported.
Access: Storefront API
Description | Example Value |
Storefront API access level |
|
Controls how the metaobjects can be accessed via the Storefront API:
PUBLIC_READ: Publicly readable via Storefront API
PRIVATE: Private access only, not available via Storefront API
Access: Admin API
Description | Example Value |
Admin API access level |
|
Controls how the metaobjects can be accessed via the Admin API:
MERCHANT_READ: Merchant read access only
MERCHANT_READ_WRITE: Merchant read and write access
PUBLIC_READ_WRITE: Public read and write access
Capability: Active-draft status
Description | Example Value |
Whether metaobjects can have active/draft status |
|
TRUE: Metaobjects can be saved as drafts or published as active
FALSE: Metaobjects are always active when created
Capability: Translations
Description | Example Value |
Whether metaobjects support translations |
|
TRUE: Metaobjects can be translated into multiple languages
FALSE: Metaobjects do not support translations
Capability: Publish entries as web pages
Description | Example Value |
Whether metaobjects can be published as web pages |
|
TRUE: Metaobjects can be published as standalone web pages with URLs
FALSE: Metaobjects cannot be published as web pages
Capability: Online Store URL Handle
Description | Example Value |
URL handle for accessing metaobjects as web pages |
|
The URL handle defines the path segment used when publishing metaobjects as web pages on the Online Store. For example, with a handle of faqs, metaobjects would be accessible at https://your-store.myshopify.com/pages/faqs/{entry-handle}.
On import:
If not provided, defaults to the metaobject definition's type
Can be set to a custom value to override the default
On export:
Displays the currently configured URL handle for the metaobject definition
Note: This field only applies when "Capability: Publish entries as web pages" is enabled.
Capability: Storefronts API access
Description | Example Value |
Whether metaobjects are accessible via Storefronts API |
|
TRUE: Metaobjects are accessible via the Storefronts API
FALSE: Metaobjects are not accessible via the Storefronts API
Row
Description | Example Value |
Row number for multi-row data |
|
Used when a metaobject definition spans multiple rows (e.g., when including multiple field definitions).
Top Row
Description | Example Value |
Whether this is the first row for this definition |
|
TRUE: This is the primary row for the definition
FALSE: This is a secondary row for additional field or validation data
Field Definitions
Field: Key
Description | Example Value |
Unique identifier for the field within the definition (Create-only) |
|
The unique key for this field within the metaobject definition. This can only be set during creation and cannot be changed later.
Field: Description
Description | Example Value |
Description of what this field stores |
|
A description explaining what this field is used for.
Field: Type
Description | Example Value |
Data type of the field (Create-only) |
|
The type of data this field can store. Common field types include:
single_line_text_field: Single line text input
multi_line_text_field: Multi-line text input
number_integer: Integer number
number_decimal: Decimal number
date: Date field
date_time: Date and time field
boolean: True/false field
color: Color picker
file_reference: File reference
url: URL field
json: JSON data
rating: Rating field
dimension: Dimension field
volume: Volume field
weight: Weight field
money: Money field
product_reference: Product reference
variant_reference: Variant reference
page_reference: Page reference
collection_reference: Collection reference
customer_reference: Customer reference
mixed_reference: Mixed reference
This field can only be set during creation and cannot be changed later.
Field: Required
Description | Example Value |
Whether this field is required when creating metaobjects |
|
TRUE: This field must be provided when creating metaobjects
FALSE: This field is optional
Field: Display Name
Description | Example Value |
Whether this field is used as the display name for metaobjects |
|
TRUE: The value of this field will be used as the display name for metaobjects
FALSE: This field is not used for the display name
Validations
Validation: Name
Description | Example Value |
Name of the validation rule |
|
The name of the validation rule being applied to a field. Common validation rules include:
min: Minimum value (for numbers) or length (for text)
max: Maximum value (for numbers) or length (for text)
regex: Regular expression pattern
file_type_options: Allowed file types (for file references)
choices: Predefined choices for the field
Validation: Type
Description | Example Value |
Data type of the validation (Export-only) |
|
The data type of the validation value. This field is export-only and cannot be imported.
Validation: Value
Description | Example Value |
Value used for the validation |
|
The value that defines the validation rule. For example, if the validation name is "min", this would be the minimum value or length allowed.
Metaobject Definition References
For fields with metaobject_reference or mixed_reference types, validations can specify which metaobject definitions are allowed. These validations use:
metaobject_definition_id: References a single metaobject definition
metaobject_definition_ids: References multiple metaobject definitions
When exporting, Altera converts these from Shopify GIDs to type handles for cross-store compatibility:
Format | Example Value |
Single definition |
|
Multiple definitions |
|
When importing, Altera accepts both formats:
Type handles (recommended):
authororauthor, brandGIDs (legacy):
gid://shopify/MetaobjectDefinition/123456
This enables you to export metaobject 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.
Export Filters
You can use these filters to limit which metaobject definitions are exported:
type: Filter by definition type (e.g.,type=author)shopify_managed: Filter by whether the definition is managed by Shopify (TRUEorFALSE)