Skip to main content

Metafields

Learn about the different metafield types and how to use them in Altera

Updated today

Altera allows you to import and export custom metafields for your Shopify products, variants, customers, and other resources using spreadsheet files. This enables bulk management of additional data fields beyond Shopify's standard properties.

Column Placement

When you export data from Altera, metafield columns appear at the end of the spreadsheet, after all standard Shopify fields. This consistent placement makes it easy to locate and work with your custom metafields.

Within each metafield group, columns are ordered as follows: SEO metafields (title_tag and description_tag) first, then pinned metafield definitions ordered by their pinned position, then remaining unpinned metafields, then Shopify standard metafields (namespaces starting with shopify) alphabetically.

When importing data into Altera, metafield columns can be placed in any order however we recommend placing them after the standard Shopify fields to keep them consistent with the order of the columns in exported files.

Column Naming Format

Metafield columns use a specific naming convention: Metafield: [namespace].[key]

Examples:

  • Metafield: custom.warranty_length

  • Metafield: inventory.supplier_code

  • Metafield: seo.meta_description

The namespace and key combination uniquely identifies each metafield in your Shopify store. If no namespace is provided in the column header, Altera defaults to using the global namespace.

Specifying Metafield Types

You can define the metafield type by adding it in square brackets at the end of the column header: Metafield: [namespace].[key] [type]

Examples:

  • Metafield: specs.weight [number_decimal]

  • Metafield: specs.is_featured [boolean]

  • Metafield: specs.related_product [product_reference]

If no type is specified, Altera will automatically detect the type from existing metafield definitions in your store.

All Supported Metafield Types

Altera supports all Shopify metafield types. Here's the complete list:

Basic Types:

  • boolean - True/false values
    Example: true or false

  • color - Color values
    Example: #ff0000 or rgb(255, 0, 0)

  • date - Date values
    Example: 2024-12-25

  • date_time - Date and time values
    Example: 2024-12-25T14:30:00

  • dimension - Measurement dimensions
    Example: {"value": 25.0, "unit": "cm"}

  • json - JSON objects
    Example: {"size": "large", "material": "cotton"}

  • json_string - JSON formatted as strings
    Example: "{\"size\": \"large\", \"material\": \"cotton\"}"

  • link - URL links
    Example: {"url": "https://example.com", "title": "Example Link"}

  • money - Currency amounts
    Example: {"amount": "19.99", "currency_code": "USD"}

  • number_decimal - Decimal numbers
    Example: 19.99

  • number_integer - Whole numbers
    Example: 42

  • integer - Whole numbers (alternative)
    Example: 42

  • decimal - Decimal numbers (alternative)
    Example: 19.99

  • rating - Rating values
    Example: {"value": 4.5, "scale_min": 1.0, "scale_max": 5.0}

  • string - Text strings
    Example: "Cotton blend fabric"

  • url - Web URLs
    Example: https://example.com

  • volume - Volume measurements
    Example: {"value": 500.0, "unit": "ml"}

  • weight - Weight measurements
    Example: {"value": 2.5, "unit": "kg"}

Text Types:

  • multi_line_text_field - Multi-line text
    Example: "This is a multi-line\ntext field with\nline breaks"

  • rich_text_field - Rich formatted text (supports HTML, Markdown, and plain text)
    Example: "<p><strong>Bold text</strong> with <em>emphasis</em></p>" or "# Title\n\n**Bold** and *italic* text"

  • single_line_text_field - Single line text
    Example: "Product care instructions"

Reference Types:

  • metaobject_reference - References to metaobjects
    Example: gid://shopify/Metaobject/123456789

  • file_reference - File references
    Example: gid://shopify/MediaImage/123456789 or image.jpg or https://cdn.shopify.com/s/files/1/0694/7382/9050/files/image.jpg or https://example.com/image.jpg

  • product_reference - Product references
    Example: gid://shopify/Product/123456789 or product handle

  • variant_reference - Product variant references
    Example: gid://shopify/ProductVariant/123456789 or [product handle].[variant title]

  • collection_reference - Collection references
    Example: gid://shopify/Collection/123456789 or collection handle

  • page_reference - Page references
    Example: gid://shopify/Page/123456789 or page handle

  • customer_reference - Customer references
    Example: gid://shopify/Customer/123456789 or customer email address

  • mixed_reference - Mixed type references
    Example: Any valid Shopify resource GID

List Types: All basic and reference types can also be used as lists by prefixing with list.. List values are formatted as JSON arrays:

  • list.boolean - Example: [true, false, true]

  • list.color - Example: ["#ff0000", "#00ff00", "#0000ff"]

  • list.date - Example: ["2024-12-25", "2024-12-26"]

  • list.date_time - Example: ["2024-12-25T14:30:00", "2024-12-25T16:00:00"]

  • list.dimension - Example: [{"value": 25.0, "unit": "cm"}, {"value": 30.0, "unit": "cm"}]

  • list.json - Example: [{"size": "small"}, {"size": "large"}]

  • list.link - Example: [{"url": "https://example.com", "title": "Link 1"}]

  • list.money - Example: [{"amount": "19.99", "currency_code": "USD"}]

  • list.number_decimal - Example: [19.99, 24.99, 29.99]

  • list.number_integer - Example: [1, 2, 3, 4, 5]

  • list.single_line_text_field - Example: ["Care instruction 1", "Care instruction 2"]

  • list.string - Example: ["Cotton", "Polyester", "Wool"]

  • list.url - Example: ["https://example1.com", "https://example2.com"]

  • list.volume - Example: [{"value": 500.0, "unit": "ml"}]

  • list.weight - Example: [{"value": 2.5, "unit": "kg"}]

  • list.product_reference - Example: ["gid://shopify/Product/123", "gid://shopify/Product/456"] or shirt-1, shirt-2

  • list.variant_reference - Example: ["gid://shopify/ProductVariant/123"] or shirt-1.Small | shirt-2.Medium

  • list.collection_reference - Example: ["gid://shopify/Collection/123"] or summer-sale, new-arrivals

  • list.page_reference - Example: ["gid://shopify/Page/123"] or about-us, contact

  • list.customer_reference - Example: ["gid://shopify/Customer/123"] or [email protected], [email protected]

  • list.file_reference - Example: ["gid://shopify/MediaImage/123"] or image1.jpg, image2.jpg

  • list.metaobject_reference - Example: ["gid://shopify/Metaobject/123"] or faq.question-1, faq.question-2

  • list.mixed_reference - Example: ["gid://shopify/Product/123", "gid://shopify/Collection/456"]

  • list.article_reference - Example: ["gid://shopify/OnlineStoreArticle/123"] or first-post, second-post

  • list.order_reference - Example: ["gid://shopify/Order/123"]

SEO Metafields

Altera provides special handling for SEO-related metafields:

  • Metafield: title_tag - Sets the SEO title for products or collections

  • Metafield: description_tag - Sets the SEO description for products or collections

Alternatively, you can use the following column headers:

  • SEO Title

  • SEO Description

Important: If no SEO title or description is provided, Shopify automatically generates them from the product's or collection's title and description. If you set a value that exactly matches the title or description, Shopify will store it as empty since it's redundant. Only values that differ from the default title/description will be saved.

Deleting Metafields

To delete a metafield from a resource, leave the corresponding cell blank in the metafield column. During import, empty cells will remove the metafield from that specific resource.

This behavior matches Matrixify's metafield deletion handling, making it easy to bulk-delete metafields by clearing values in your spreadsheet.

App-Owned Metafields from Other Apps

Some metafields on your store are created and managed by other Shopify apps. These are called app-owned metafields and live in a reserved namespace that only the owning app can read or write. You will often see them in the Shopify admin (they may even be marked as "viewable in admin"), but Altera cannot include them in exports or update them during imports.

This is a Shopify platform restriction, not an Altera limitation. Shopify removed public and cross-app access to app-owned metafields in May 2025, so no third-party app can read another app's metafields through the Admin API. "Viewable in admin" controls whether the merchant can see the field in the Shopify admin UI. It does not grant API access to other apps.

A few things to know:

  • App-owned metafields use namespaces that start with app-- (for example, app--123456--my_field). If you see that format in the Shopify admin, the metafield belongs to another app.

  • Altera exports and imports only show metafields in merchant-owned namespaces like custom, global, or any non-reserved namespace you or a merchant created yourself.

  • If you need a metafield's data to be accessible to Altera and other apps, the owning app has to store it in a merchant-owned namespace instead of its reserved one. That is a change only the app developer can make.

If you want to manage similar data yourself through Altera, you can create a separate metafield in a merchant-owned namespace (for example, custom.my_field) and import values into it. The trade-off is that the original app will not read from your custom metafield unless it adds support for it.

How Altera Handles Different Metafield Types

Altera provides intelligent parsing and normalization for metafield values entered in spreadsheets. The system automatically converts user-friendly formats into Shopify's expected format for each metafield type.

Boolean (boolean)

Boolean metafields accept various representations of true/false values:

True values: true, 1, yes, on False values: false, 0, no, off

Color (color)

Color metafields accept various input formats and are normalized to hex format:

Accepted formats:

  • c9f5f6 - Without # prefix

  • #c9f5f6 - With # prefix

  • #C9F5F6 - Uppercase letters

Output: Always normalized to lowercase hex format with # prefix (e.g., #c9f5f6)

Date (date)

Date metafields use flexible parsing to handle various input formats:

Accepted formats:

  • 2024-12-25 - ISO format

  • December 25, 2024 - Natural language

  • 25/12/2024 - Day/month/year

  • 12/25/2024 - Month/day/year

Output: ISO formatted date string (2024-12-25)

Date Time (date_time)

DateTime metafields use flexible parsing to handle various input formats:

Accepted formats:

  • 2024-12-25T14:30:00 - ISO format

  • December 25, 2024 2:30 PM - Natural language

  • 25/12/2024 14:30 - Combined format

Output: ISO formatted datetime string (2024-12-25T14:30:00)

Dimension (dimension)

Dimension metafields parse value and unit combinations:

Accepted formats:

  • 25.4mm, 10cm, 2.5m, 12in, 3ft

  • Supported units: mm/millimeter/millimeters, cm/centimeter/centimeters, m/meter/meters, in/inch/inches, ft/foot/feet

Output: JSON format like {"value": 25.4, "unit": "MILLIMETERS"}

JSON (json)

JSON metafields accept either valid JSON strings or JavaScript object notation:

Accepted formats:

  • {"size": "large", "material": "cotton"} - Standard JSON

  • {size: "large", material: "cotton"} - JavaScript object notation

JSON String (json_string)

JSON string metafields work the same as JSON fields but store the value as a string.

Link metafields accept plain URLs or JSON format. Plain URLs are automatically converted to Shopify's JSON structure.

Accepted formats:

Output: JSON format like {"text": "", "url": "https://example.com"}

Note: The link type is different from the url type. The url type stores plain URL strings and does not require JSON formatting.

Money (money)

Money metafields support flexible input formats and are converted to Shopify's JSON structure:

Accepted formats:

  • 10.50 USD - Amount with currency

  • 15.99 - Amount only (uses shop's default currency)

  • $10.50 - With dollar sign

  • 1,210.50 USD - With thousand separators

  • 22. USD - Trailing decimal point

Output: JSON format like {"amount": 10.50, "currency_code": "USD"}

Multi Line Text Field (multi_line_text_field)

Multi-line text metafields accept plain text with line breaks preserved.

Number Decimal (number_decimal / decimal)

Decimal number metafields accept numeric values like 19.99.

Number Integer (number_integer / integer)

Integer number metafields accept whole number values like 42.

Rating (rating)

Rating metafields accept plain numbers or JSON format. Plain numbers are automatically wrapped with scale values from the metafield definition.

Accepted formats:

  • 4.5 - Plain number (automatically wrapped with scale from definition)

  • {"value": "4.5", "scale_min": "1.0", "scale_max": "5.0"} - Full JSON format

Output: JSON format like {"value": "4.5", "scale_min": "1.0", "scale_max": "5.0"}

Note: When using a plain number, the scale_min and scale_max values are read from your metafield definition's validation settings. If no validations are set, defaults of 1.0 and 5.0 are used.

Rich Text Field (rich_text_field)

Rich text metafields support various input formats and convert them to Shopify's rich text JSON:

Accepted formats:

  • Plain text - Automatically wrapped in paragraph tags

  • HTML - Converted to rich text structure (e.g., this is <b>important</b>)

  • Markdown - Parsed and converted to rich text format

  • JSON - If already in Shopify's rich text JSON format, passed through unchanged

Input Format Detection:

  • Content starting with { is treated as JSON

  • Content containing HTML tags (like <b>, <p>, <em>) is processed as HTML

  • All other content is treated as Markdown (including plain text)

Markdown Examples:

  • Headers: # Main Title, ## Subtitle

  • Bold/Italic: **bold text**, *italic text*

  • Lists: * Item 1, * Item 2

  • Links: [Link text](https://example.com)

HTML Examples:

  • <p>Paragraph with <strong>bold</strong> text</p>

  • this is <b>important</b> information

  • some text with <em>emphasis</em>

Output: Shopify's rich text JSON structure

Single Line Text Field (single_line_text_field)

Single-line text metafields accept plain text values.

URL (url)

URL metafields accept web address values.

Volume (volume)

Volume metafields parse value and unit combinations:

Accepted formats:

  • 500ml, 1.5l, 2gal, 1qt

  • Supported units: ml/milliliter/milliliters, l/liter/liters, gal/gallon/gallons, qt/quart/quarts

Output: JSON format like {"value": 500.0, "unit": "MILLILITERS"}

Weight (weight)

Weight metafields parse value and unit combinations:

Accepted formats:

  • 2.5kg, 500g, 1.2lb, 8oz

  • Supported units: g/gram/grams, kg/kilogram/kilograms, lb/pound/pounds, oz/ounce/ounces

Output: JSON format like {"value": 2.5, "unit": "KILOGRAMS"}

Reference Fields

Reference metafields (product_reference, variant_reference, collection_reference, page_reference, file_reference, metaobject_reference, customer_reference, mixed_reference) accept multiple input formats:

Import formats:

  • Full Shopify GIDs: gid://shopify/Product/123456789

  • Resource handles: cotton-shirt (for products, collections, pages) or email addresses (for customers)

  • Numeric IDs: 123456789 (automatically converted to GIDs)

Export format:

Reference metafields export as handles or filenames instead of GIDs for better portability between stores:

  • product_reference → product handle (e.g., cotton-shirt)

  • collection_reference → collection handle (e.g., summer-collection)

  • page_reference → page handle (e.g., about-us)

  • file_reference → filename (e.g., product-image.jpg)

  • customer_reference → customer email (e.g., [email protected])

  • metaobject_reference → metaobject handle (e.g., faq-item-1)

This allows you to export data from one store and import it to another without manually converting GIDs.

File Reference Format (file_reference)

File reference metafields support multiple input formats:

Accepted formats:

How it works:

  • If you provide a GID, it's used directly

  • If you provide a filename (no slashes or URL scheme), Altera searches for an existing file with that name

  • If you provide a Shopify CDN URL from your store, Altera extracts the filename and looks up the existing file

  • If you provide any other URL, Altera uploads the file to Shopify and uses the returned GID

Works the same for list.file_reference values and when using separator-based lists.

Variant Reference Format (variant_reference)

  • Export format: [product handle].[variant title] for readability and portability between stores.

  • Import accepts: full GIDs, numeric IDs, and the handle.title format.

  • If the variant title contains a comma, escape it with a backslash: e.g., shirt-1.Small \, Red.

  • Works the same for list.variant_reference values and when using separator-based lists.

List Fields

List metafields support multiple input formats with automatic separator detection. All basic and reference types can be used as lists by prefixing with list. (e.g., list.color, list.product_reference).

Input Formats

JSON Array Format:

["item1", "item2", "item3"]

Separated Values:

Altera automatically detects the separator used in your data:

  • Comma-separated: item1, item2, item3

  • Semicolon-separated: item1; item2; item3

  • Pipe-separated: item1 | item2 | item3

  • Newline-separated: items on separate lines

  • Tab-separated: items separated by tabs

The system counts non-escaped occurrences of each separator and picks the one with the highest count. If no separators are found, it defaults to comma separation. Malformed JSON arrays (starting with [ but invalid JSON) fall back to separator-based parsing.

Escaping Separators

If a value itself contains the separator character, escape it with a backslash. For example, variant titles with commas:

hoodie.Red\, Large, hoodie.Green\, Small, t-shirt.Blue

This produces three items: hoodie.Red, Large, hoodie.Green, Small, and t-shirt.Blue. The escaped commas (\,) are preserved within each item while unescaped commas act as separators.

Handle Resolution

List reference types resolve handles the same way as their single-value counterparts. Each item in the list is individually processed according to its base type:

  • list.product_reference: accepts product handles (e.g., shirt-1, shirt-2)

  • list.variant_reference: accepts product_handle.variant_title format (e.g., shirt-1.Small | shirt-2.Medium)

  • list.collection_reference: accepts collection handles (e.g., summer-sale, new-arrivals)

  • list.page_reference: accepts page handles (e.g., about-us, contact)

  • list.customer_reference: accepts email addresses (e.g., [email protected], [email protected])

  • list.file_reference: accepts filenames or URLs (e.g., image1.jpg, image2.jpg)

  • list.metaobject_reference: accepts type.handle format (e.g., faq.question-1, faq.question-2)

  • list.article_reference: accepts article handles (e.g., first-post, second-post)

All reference formats accepted by single reference fields (GIDs, numeric IDs, handles) work the same way in lists. If a handle cannot be resolved, that item is excluded from the final list and an import warning is shown.

List Processing

  • Each item is normalized according to its base type (e.g., list.money items are parsed as money values, list.color items are normalized to hex)

  • Empty items are automatically filtered out

  • Whitespace around each item is trimmed

Examples

  • list.color: #ff0000, #00ff00, #0000ff → ["#ff0000", "#00ff00", "#0000ff"]

  • list.money: 10.50 USD; 15.99 EUR → [{"amount": 10.50, "currency_code": "USD"}, {"amount": 15.99, "currency_code": "EUR"}]

  • list.product_reference: shirt-1, shirt-2 → ["gid://shopify/Product/123", "gid://shopify/Product/456"]

  • list.variant_reference: shirt-1.Small | shirt-2.Medium → ["gid://shopify/ProductVariant/123", "gid://shopify/ProductVariant/456"]

Working with Metafield Data

When editing metafield values, you can use user-friendly formats as described above. Altera will automatically normalize them to Shopify's expected format during import.

Example

Handle

Title

Metafield: custom.material

Metafield: custom.care_instructions

shirt-1

Cotton Shirt

Cotton

Machine wash cold

shirt-2

Silk Blouse

Dry clean only

shirt-3

Linen Top

Linen

In this example:

  • shirt-1: Both metafields will be updated

  • shirt-2: Material metafield will be deleted, care instructions updated

  • shirt-3: Care instructions metafield will be deleted, material updated

Related Articles
Metafield Definition Fields
Metaobject Fields
How to Transfer Metafields Between Shopify Stores
Translation Fields
How to Import and Export Google Shopping Metafields in Shopify
Did this answer your question?