Metafields
Metafields are used to store additional or customized information that is not available by default in Shopify, and are therefore considered supplementary fields to enrich the base data.
Sales Layer allows metafields to be synchronized from the connector, taking into account that:
- The metafield must be created in Shopify before being sent from the connector.
- The metafield must be defined in Shopify.
Creating metafields in Shopify
By accessing Settings → Metafields and Metaobjects, you can choose between Products, Variants, and Collections.
To create metafields in the selected table, click the Add definition button.
After entering the metafield name, the Namespace and key will automatically appear below. It can be opened and customized by clicking on it if needed.
Finally, Select type allows you to define the metafield by choosing one of the predefined options.
For more information on managing metafields, consult Shopify’s official documentation here.
How to map a metafield in the channel
To assign a metafield in the Sales Layer connector, the syntax must be used as follows:
"metafields” + "_" + namespace + "_" + key
For example, the following metafield configured in Shopify would be named "metafields_saleslayer_expirydate" in the connector:
Attention: The character “_” must not be used in the metafield namespace.
Supported metafields
For more information on each metafield, consult Shopify’s official documentation here.
| Type | Description | Example Value |
|---|---|---|
| boolean | True/false value. | true |
| collection_reference | Reference to a store collection. In SL it can be mapped directly with the related item, keeping in mind that Shopify only allows one value. To link multiple references at once, use list.collection_reference. | gid://shopify/Collection/1 |
| color | Hexadecimal color code. For lists, use list.color. | #fff123 |
| date | Date in ISO 8601 format without assumed time zone. | 2022-02-02 |
| date_time | Date/time in ISO 8601 format without assumed time zone (default GMT). For lists, use list.date_time. | 2022-01-01T12:30:00 |
| dimension | A value and length unit (in, ft, yd, mm, cm, m). For lists, use list.dimension. | { "value": 25.0, "unit": "cm"} |
| file_reference | Reference to a file in the store. In SL it can be mapped directly with the image/file field, but Shopify only allows one value. For multiple references, use list.file_reference. Image metafields are separate from standard product images. | gid://shopify/MediaImage/123 |
| JSON | JSON value (object, array, string, number, boolean, or null). | { "ingredient": "flour", "amount": 0.3} |
| link | Text with URL, can store link content. For lists, use list.link. | {"text": "Learn more", "url": "https://shopify.com"} |
| money | Numeric amount with store currency code. | {"amount": "5.99", "currency_code": "CAD"} |
| multi_line_text_field | Multiline text field. | Ingredients / Flour / Water / Milk |
| number_decimal | Decimal number within +/-9999999999999.999999999. For lists, use list.number_decimal. | 10.4 |
| number_integer | Integer within +/-9,007,199,254,740,991. For lists, use list.number_integer. | 10 |
| page_reference | Reference to a store page (exact value required). | gid://shopify/OnlineStorePage/1 |
| product_reference | Reference to a store product. In SL it can be mapped directly with the related item, but Shopify only allows one value. For multiple references, use list.product_reference. | gid://shopify/Product/1 |
| rating | Rating on a defined scale (validations required for min/max). For lists, use list.rating. | { "value": "3.5", "scale_min": "1.0", "scale_max": "5.0"} |
| rich_text_field | Rich text supporting headings, lists, links, bold, and italics. More info about Rich text formatting. | { "type": "root", "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Bold text.", "bold": true } ] } ] } |
| single_line_text_field | Single-line text field. For lists, use list.single_line_text_field. | VIP shipping method |
| URL | URL with allowed schemes: https, http, mailto, sms, tel. For lists, use list.url. | https://www.shopify.com |
| variant_reference | Reference to a product variant. In SL it can be mapped directly with the related item, but Shopify only allows one value. For multiple references, use list.product_reference. | gid://shopify/ProductVariant/1 |
| volume | Value and volume unit (ml, cl, l, m3, us_fl_oz, us_pt, us_qt, us_gal, imp_fl_oz, imp_pt, imp_qt, imp_gal). For lists, use list.volume. | { "value": 20.0, "unit": "ml"} |
| weight | Value and weight unit (oz, lb, g, kg). For lists, use list.weight. | { "value": 2.5, "unit": "kg"} |
For metafields referenced with the list-value option, the metafield type must be defined in Shopify in order to select whether it should be a single value or a list of values.
Important note: Multi-language metafield types outside of those listed above must be tested by the client to determine if they are supported. These are considered outside the scope of the functionality.
The metafields included by default in the connector, metafields_global_title_tag and metafields_global_description_tag, are considered legacy and are maintained for backward compatibility. Shopify recommends using seo_title and seo_description instead. For more details on configuration, refer to the following link.
