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
By default, Altera will not export Shopify-managed metaobject definitions during exports.
Shopify manages certain metaobject definitions internally (typically with type names starting with shopify--
, such as shopify--color-pattern
). These are used for Shopify Product Taxonomy and are system-managed definitions that cannot be created, updated, or modified through the API.
Why they're excluded by default:
Shopify-managed definitions cannot be imported back into stores as the API does not allow it
Attempting to import them will result in errors (MOBD001)
If you need to export them anyway: You can include Shopify-managed definitions in your export by removing the "Is managed by Shopify" filter when configuring your export. This might be useful for documentation or analysis purposes, but remember that these definitions cannot be imported back into any store.
What you can import: Only custom metaobject definitions (those not managed by Shopify) can be successfully imported through Altera.
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 fail 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: 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
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.
Export Filters
You can use these filters to limit which metaobject definitions are exported:
type
: Filter by definition typeupdated_at
: Filter by last update date