Skip to main content
Print

Shopify Metafield Field Plugin

The format Send Shopify-Metafield fills metafields of products, variants and collections. The Shopify station template uses it for all metafield rows. The setup is on Shopify Transmitter.

Available from: 1.20.0

Configuration in Shopify

The transmitter fills existing metafields, so the metafield definitions must be created in Shopify (Settings > Custom data), for the right owner: Products, Variants or Collections.

Metafield definitions of products in Shopify

From the definition you need:

  • the key (by default the name) and the namespace (usually custom)
  • the type, and whether it holds one value or a list
  • for the type Metaobject: the type of the metaobject definition
Metafield definition of the type metaobject reference

Configuration of the datamap row

In the datamap, a metafield row has the key metafields|your-name. If the metafield is language dependent, add |{StoreView}: metafields|your-name|{StoreView}. The name is only used in the log.

Where the row sits decides the owner of the metafield:

RowOwner in ShopifyDefinition with owner
metafields|… in the products datamapthe productProducts
simpleproduct|metafields|… in the products datamap, metafields|… in the variants datamapthe variant (for a simple product: its default variant)Variants
metafields|… in the collections datamapthe collectionCollections

Variant metafields of simple products: available from 1.19.9 · 1.20.0

Selecting the format Send Shopify-Metafield

Configuration of the format

Enter the values of the Shopify definition: Metafield Type (1), Key (Name) (2), Namespace (3) and Value Type (One value or List of values), and, depending on the type, Metaobject-Type or Minimum rating / Maximum rating.

Format settings for a translated single line text

What the value has to look like:

Metafield typeValue
Single line text, Multi-line text, IDtext
Rich textShopify’s rich text JSON, e.g. {"type":"root","children":[{"type":"paragraph","children":[{"type":"text","value":"Hello"}]}]}
Integer, Decimala number with a dot, e.g. 8.5; 0 is a value
True or falsetrue or false (also 1 or 0)
DateYYYY-MM-DD
Date and TimeYYYY-MM-DDTHH:MM:SS
Colorhex code with six digits, e.g. #FFFFFF (#FFF doesn’t work)
URLwith one of the schemes http, https, mailto, sms, tel
LinkJSON with text and URL, e.g. {"text": "Size chart", "url": "https://example.com"}
JSONa valid JSON string
Dimension, Volume, WeightJSON with a numeric value and a unit, e.g. {"value": 33.0, "unit": "cm"}
MoneyJSON with a numeric amount and the shop currency, e.g. {"amount": "149.95", "currency_code": "EUR"}
Ratinga number between Minimum rating and Maximum rating; the format builds the rating JSON
Product, Collectionthe PIM identifier of the product or collection
Product variantthe SKU of the variant
Filethe file name of a file uploaded with upload (see Shopify Mediaupload Field Plugin)
Metaobjectthe handle of the entry; the type comes from the setting Metaobject-Type

For the reference types (Product, Collection, Product variant, File, Metaobject) the format finds the Shopify ID itself. The template has a configured row for every type.

A list of product references: Metafield Type Product (1) and Value Type List of values (2):

Format settings for a list of product references

A metaobject reference: Metafield Type Metaobject (1) and the type of the metaobject definition in Metaobject-Type (2):

Format settings for a metaobject reference

Money: Metafield Type Money (1), and as value a JSON string (2) with the amount and the currency code:

Format settings for a money metafield
Metafields of a product in Shopify

Important:

  • An empty value deletes the metafield in Shopify (from 1.19.7 · 1.20.0).
  • If one metafield value is invalid, Shopify rejects the whole product, not only that metafield.
  • For List of values, a comma-separated text is one value. Split it into a list first; the list rows of the template show how. Skip empty values: an empty list entry is rejected.
  • Export referenced products, collections and files first. References to records created in the same run are found in the next run.
  • In a list, references that cannot be found are left out. A single reference that cannot be found keeps the metafield unchanged and logs “reference … was not found in Shopify” (from 1.21.20; before, the metafield was emptied).
  • Shopify returns units by name: cm is shown as CENTIMETERS.

Variant and collection metafields

Variant and collection rows work the same way; only the definition’s owner differs:

Metafield row of the variants datamap

Metafield references without the format

Rows built by hand (see Legacy) can reference records with a prefix in the value:

Reference toValueAvailable from
product@productRef:{PIM identifier}1.19.1 · 1.20.0
variant@variantRef:{SKU}1.19.1 · 1.20.0
collection@collectionRef:{PIM identifier}1.19.1 · 1.20.0
file@mediaRef:{file name}1.19.1 · 1.20.0
metaobject entry@metaobjectRef:{definition type}|{handle}1.19.3 · 1.20.0

You can also send the Shopify ID directly.

Legacy: metafield as an array

Before the format, every metafield was configured with Create an array and the keys namespace, key and value (a string; lists as a JSON-encoded array). With the additional key type (e.g. single_line_text_field), the metafield also works without a definition in Shopify.

The key type: available from 1.19.9 · 1.20.0

Metafield configured as an array with namespace, key, value and type

Related products (Search & Discovery)

The Shopify app Search & Discovery shows related and complementary products on the product page. It reads them from product metafields in its own namespace. The previous template has a deactivated row for this:

  • namespace shopify--discovery--product_recommendation, key related_products or complementary_products
  • the value is the list of the related products, read from a product reference attribute
Row for the related products of Search & Discovery

Alternatively, use a row with the format Send Shopify-Metafield: type Product, List of values, with this namespace and key.

Important:

  • The app Search & Discovery must be installed in the shop; it creates the metafield definitions.
  • The referenced products must already be in Shopify. A product without references gets no metafield.
Was this article helpful?
How can we improve this article?
Please submit the reason for your vote so that we can improve the article.
Table of Contents