Articles on: Shopify

Custom Data (Metafield)

How to Map Custom Data (Metafield) Field

Sync, create, and update Shopify product and variant metafields using feed column data or static fixed values. This feature enables merchants to enrich store catalogs with technical specifications, custom attributes, and multi-language translations without manual theme coding.

Available on: ✔️ Add | ✔️ Update | ✔️ Export

Interactive Walkthrough

Explore this step-by-step interactive demo to learn how to configure custom data metafields in Stock Sync.

How to Set Up Custom Data (Metafield) Mapping

Go to App → Feed Settings → Step 2: Field Mapping

Add Field: Select Metafield (e.g., Metafield 1, Metafield 2, etc.) from the field dropdown list.
Select Metafield Definition: Choose the target Shopify Namespace and Key from the dropdown menu.
Map Source Column: Select the corresponding column name or index from your feed file, or enter a fixed value.
Configure Smart Settings: Click the Settings (gear icon) next to the mapped metafield to set blank handling, find/replace rules, or content types.

If the metafield definition does not yet exist in your Shopify store, Stock Sync automatically creates it upon syncing.

Displaying newly created metafields on your storefront requires adding Liquid code snippets or theme blocks inside your Shopify theme editor.

Custom Data (Metafield) Smart Settings / Detailed Breakdown

1. Metafield Namespace and Key

Select the specific metafield from your store using the dropdown menu. The list displays the metafield name, key, owner type (Product or Variant), and content type.

Preset Shopify system metafields (such as shopify.color-pattern) may appear in the dropdown but are read-only in Shopify and cannot be updated via Stock Sync.

Need to update Google Shopping attributes? Check our [Update Google Fields Using Metafields Guide] for setup details.

2. Metafield Owner

Identifies whether the metafield belongs to the Product level or the Variant level.

This field is prefilled automatically based on your Shopify Admin metafield definition.

3. Skip Update When Feed Value Is Blank

Prevents overwriting existing Shopify metafield values when the corresponding feed file cell is empty.

This option is enabled by default to protect existing store data from accidental deletion.

Numeric zero (0 or '0') is evaluated as an active value and is not considered blank.

4. Remove Metafield When Value Is Blank in Feed

Automatically clears and removes the metafield value in Shopify if the feed cell is empty, preventing unwanted hyphens (-) from appearing.

Enable this toggle if you want blank feed cells to completely erase the metafield on Shopify.

5. Only Update if Current Metafield Is Empty

Restricts updates exclusively to products or variants that do not currently have a metafield value assigned in Shopify.

Available only for Shopify Update feeds.

Use this setting to backfill missing metafield values across your catalog without modifying products that already have values.

6. Find

Searches for specific terms, characters, or patterns in the feed value before writing it to Shopify.

Separate multiple search terms or phrases with commas.

Supports wildcards (*) and regular expressions. For example, entering *man matches woman and manicure.

To strip HTML links, use a regular expression pattern such as *<a href=.?>,<a id=.?>,</a>*.

7. Replace With

Replaces the characters or phrases identified in the Find field with replacement values.

Separate multiple replacement values with commas to correspond with your search terms in Find.

Use dynamic column replacement syntax like {{description}} to insert values dynamically from other feed columns.

8. Translation From

Select the source language of the feed value for automated translation.

Supports over 10 global languages.

Automated translation is only supported for the Single line text content type.

9. Translation To

Select the target language to which the feed value should be translated before saving to Shopify.

Available exclusively for Single line text metafields.

10. Metafield Content Type

Defines the data structure required by Shopify. The data type selected in Stock Sync must match the definition in Shopify Admin.

Example Content Type Definitions:

Content Type	Description	Example Value
Single line text	A single-line text field.	`This item contains dairy products.`
Multi-line text	A multi-line text field supporting line breaks.	`Ingredients: Flour, Water, Milk, Eggs`
Integer	A whole number in the range of +/-9,007,199,254,740,991.	`10`
Decimal	A number with decimal places in the range of +/-9999999999999.999999999.	`10.4`
Date	A date in ISO 8601 format without a presumed timezone (`YYYY-MM-DD`).	`2026-10-01`
Date and time	A date and time in ISO 8601 format. Current date timestamps match store timezone.	`2026-10-01T12:30:00`
URL	A valid web link using supported schemes: `https`, `http`, `mailto`, `sms`, `tel`.	`https://www.shopify.com`
JSON string	A JSON-formatted string. Deprecated in Shopify Liquid but maintained for legacy compatibility.	`[{"k": "v1"}, {"k": "v2"}]`
True or False	Boolean value with two states: `true` or `false`.	`TRUE`
Color	Hexadecimal color code.	`#fff123`
Weight	A numeric value and valid unit of weight (`oz`, `lb`, `g`, `kg`).	`{"unit": "kg", "value": 2.5}`
Volume	A numeric value and valid unit of volume (`ml`, `cl`, `l`, `m3`, `us_fl_oz`, `us_pt`, `us_qt`, `us_gal`, `imp_fl_oz`, `imp_pt`, `imp_qt`, `imp_gal`).	`{"unit": "ml", "value": 20.0}`
Dimension	A numeric value and valid unit of length (`in`, `ft`, `yd`, `mm`, `cm`, `m`).	`{"unit": "cm", "value": 25.0}`
Rating	A rating score measured on a defined numerical scale.	`{"value": "4.5", "scale_min": "1.0", "scale_max": "5.0"}`

Unsupported Types: Reference metafields (Product, Page, File, Variant, Metaobject) and list reference types (e.g., list.metaobject_reference) cannot be mapped or updated.

Example Metafield Structure:

Namespace	Key	Value	Result
`EstimatedTimeArrival`	`ETA`	`1 days`	Assigned to product or variant based on metafield owner.
`EstimatedTimeArrival`	`ETA`	`2 days`	Assigned to product or variant based on metafield owner.

Always inspect your raw feed file using a plain text editor (Notepad or TextEdit). Spreadsheet software like Excel can alter date formats and numeric precision.

11. Default Value If Cell Is Blank

Assigns a fallback value to the metafield whenever the feed file cell is empty.

The default value field cannot be left blank when this option is enabled.

Useful for ensuring that required store metafields always contain a standard placeholder.

12. Append New Metafield Without Overwriting

Appends incoming values from the feed file to existing values in Shopify instead of replacing them.

Available on Update feeds exclusively for single-line text list values.

Check our [Append New Metafield Guide] for step-by-step instructions.

13. Metafield Validation Errors

Metafield updates fail if the feed data does not comply with the validation constraints set in Shopify Admin.

Common Causes:

Feed cells are blank for metafields configured as Required in Shopify.
Numeric values fail minimum or maximum limits (e.g., value must be >= 1).
Values do not match pre-defined choice lists configured in the Shopify definition.
Mismatch between owner types (e.g., sending product-level data to a variant metafield).

How to Resolve Validation Errors:

Check the Stock Sync Activity Log to identify the rejected metafield and SKU.
In Shopify Admin, navigate to Settings → Custom data and select the affected metafield.
Review validation settings (adjust constraints, expand choices, or uncheck "Required").
Re-run your sync after updating Shopify settings or feed data.

Key Rules & Technical Details

Strict Data Type Matching: Stock Sync content types and Shopify metafield definitions must match identically (e.g., numeric values require Decimal or Integer, not Single line text).
Unsupported Reference Types: Reference fields including Product, Page, File, Variant, Metaobject, and list.metaobject_reference cannot be updated.
Read-Only System Fields: Shopify internal system definitions (e.g., shopify.color-pattern) cannot be modified through the API.
Empty Cell vs Zero: Numerical zero (0) is treated as a valid value; only null or empty strings trigger blank handling rules.
Multi-Column Mapping: Mapping multiple feed columns to a single metafield is supported only when using multi-line text or list content types.

Troubleshooting Steps

Issue: Sync fails with a metafield validation error → Solution: Check Shopify Admin (Settings → Custom data) to ensure incoming values satisfy min/max constraints, allowed choices, and required rules.
Issue: Date or decimal formatting gets distorted → Solution: Open your feed file in a raw text editor (such as Notepad) to verify formatting, as spreadsheet software like Excel can modify date strings and decimal separators.
Issue: Metafield does not appear on the storefront after syncing → Solution: Confirm the value updated in Shopify Admin under product metafields, then add the appropriate theme block or Liquid snippet to your theme template.

Good Articles to Continue

[How to Update Google Fields Using Metafields] → Map and sync Google Shopping product attributes via Shopify metafields.
[How to Set Metafield True and False Values] → Correctly format boolean flags for Shopify metafields.
[How to Append New Metafield Values] → Append values to list metafields without replacing existing store data.
[How to Update Metafield Date Content Type] → Format dates according to ISO 8601 requirements.

Updated on: 16/10/2026

Was this article helpful?

Thank you!