Skip to main content

Metafields

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

Updated yesterday

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.

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

  • 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"]

  • list.variant_reference - Example: ["gid://shopify/ProductVariant/123"]

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

  • list.collection_reference - Example: ["gid://shopify/Collection/123"]

  • list.page_reference - Example: ["gid://shopify/Page/123"]

  • list.file_reference - Example: ["gid://shopify/MediaImage/123"]

  • list.metaobject_reference - Example: ["gid://shopify/Metaobject/123"]

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

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: Shopify has special behavior for these fields. If you set a value that exactly matches the product 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.

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 URL values with optional title text.

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 standard numeric formats:

Accepted formats:

  • 19.99 - Decimal numbers

  • 1,234.56 - With thousand separators (commas removed automatically)

Number Integer (number_integer / integer)

Integer number metafields accept whole number formats:

Accepted formats:

  • 42 - Whole numbers

  • 1,234 - With thousand separators (commas removed automatically)

Rating (rating)

Rating metafields accept rating values with scale information.

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, mixed_reference) accept multiple input formats:

Import formats:

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

  • Resource handles: cotton-shirt (for products, collections, pages)

  • 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)

  • 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:

  • GID format: gid://shopify/MediaImage/123456789 - Direct Shopify file GID

  • Filename: image.jpg - Looks up existing file by filename in your Shopify store

  • Shopify CDN URL: https://cdn.shopify.com/s/files/1/0694/7382/9050/files/image.jpg - Extracts filename from CDN URL and looks up existing file (only if URL is from your store)

  • External URL: https://example.com/image.jpg - Uploads the file to Shopify and returns the GID

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:

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: item1\nitem2\nitem3

  • Tab-separated: item1 item2 item3

Smart Separator Detection: The system analyzes the content and chooses the separator with the highest occurrence count. If no separators are found, it defaults to comma separation.

List Processing:

  • Each item in the list is processed according to its base type (e.g., list.money items are processed as money values)

  • Empty items are automatically filtered out

  • Malformed JSON arrays fall back to separator-based parsing

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 → ["shirt-1.Small", "shirt-2.Medium"]

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
How to Update SEO Meta Titles and Descriptions for Shopify Products
Differences between Altera and Matrixify
Did this answer your question?