Metafields can be added to Collections, Products and Product Variants. Metafields help you to customize the functionality and appearance of your Shopify store. The Shopify Connector has a limit of 250 metafields pr. Item (Collections, Products and Product Variants).
The mapping of Metafields will create a Metafield Definition. If the Name is not specified, the Metafield Definition name will be created with the key as the name and the name will not be updated and can be modified from the Shopify Admin page.
| Mapping to field | Output Kind | Description |
|---|---|---|
|
Metafield|<namespace>|<key> Metafield|<namespace>|<key>|<type> Metafield|<namespace>|<key>|<type>|<name> |
Field |
Product metafield parameter. “namespace” and “key” combined value must be unique. “namespace” must have min 2 chars, max 20 chars and allowed characters are: A-Za-z0-9_.~-@#*$. “key” must have min 3 chars, max 30 chars and allowed characters are A-Za-z0-9_.~-@#*$ “type” parameter may have many values. Refer to the below Value types in order to see all supported values. Type is optional. If not defined the ‘single_line_text_field’ type will be used by default. “name” parameter is the name for the Metafield Definition |
| Metafield|<namespace>|<key>|<type>|<name>@ShopifyUnit | Attribute |
Get units from a string feature instead of using Perfion Feature Unit or json format. This only works for Dimension, |
|
Metafield|<namespace>|<key>|file_reference Metafield|<namespace>|<key>|list.file_reference Metafield|<namespace>|<key>|file_reference|<name> |
Attachment(Url) |
A file stored in Perfion can be attached to a Metafield via the Attachment(Url). The file will be uploaded to Shopify Content Files as a “Generic File” if it does not exist. If a file with the same name already exist, the existing file from the Content Files will be attached to the Metafield. Shopify has some unknown rules for renaming files e.g. spaces are replaced with underscore, avoid to use filenames with special characters. |
Value types
| Type | Description |
| boolean |
A true or false value or use numbers 0 and 1. Example: “true” |
| color |
The hexadecimal code for a color including leading # char. Example: “#fff123” |
| date |
A date in ISO 8601 format without a presumed time zone. Example: “2021-02-02” |
| date_time |
A date and time in ISO 8601 format without a presumed time zone. Example: “2021-01-01T12:30:00” |
| dimension |
A number value and a unit. Unit is by default the unit at the Perfion Feature, but can be set via an attribute @ShopifyUnit or the value can be a json string like { "unit": "cm", "value": 25.0 } Valid unit values: in, ft, yd, mm, cm, m. Example: 25.0 or { "unit": "cm", "value": 25.0 } |
| json |
A JSON-formatted string. The json is translatable. Example: “[{ "k": "v1" }, { "k": "v2" }]” |
| metaobject_reference | A reference to a metaobject Id entry like “gid://shopify/Metaobject/121499910317” |
| money |
A numeric value and a unit for the currency code that matches the store's currency. Unit is by default the unit at the Perfion Feature, but can be set via an attribute @ShopifyUnit or the value can be a json string like { "amount": "5.99", "currency_code": "CAD" } Valid unit values: currency code in the shop. Example: 5.99 or { "amount": "5.99", "currency_code": "CAD" } |
|
multi_line_text_field
|
A multi-line text field. The multi_line_text_field is translatable. Example: “Item list: Table Chair” |
| number_decimal |
A number with decimal places in the range of +/-9999999999999.999999999. Example: “10.4” |
| number_integer |
A whole number in the range of +/-9,007,199,254,740,991. Example: “10” |
| rating |
A rating measured on a specified scale. This is a JSON-formatted string. Example: { "value": "3.5", "scale_min": "1.0", "scale_max": "5.0" } |
| rich_text_field | A rich text field supporting headings, lists, links, bold, and italics as json string. Learn more about rich text formatting. The Title is translatable. |
|
single_line_text_field
|
A single-line text field. The single_line_text_field is translatable. Example: “Some text” |
| url |
A URL with one of the allowed schemes: https, http, mailto, sms, tel. The url is translatable. Example: “Start and grow your e-commerce business - 3-Day Free Trial ” |
| volume |
A number value and a unit. Unit is by default the unit at the Perfion Feature, but can be set via an attribute @ShopifyUnit or the value can be a json string like { "unit": "cm", "value": 25.0 } Valid unit values: ml, cl, l, m3 (cubic meters), us_fl_oz, us_pt, us_qt, us_gal, imp_fl_oz, imp_pt, imp_qt, imp_gal. Example: 25.0 or { "unit": "ml", "value": 20.0 } |
| weight |
A number value and a unit. Unit is by default the unit at the Perfion Feature, but can be set via an attribute @ShopifyUnit or the value can be a json string like { "unit": "cm", "value": 25.0 } Valid unit values: oz, lb, g, kg Example: 25.0 or { "unit": "ml", "value": 20.0 } |
Reference types
| Type | Description |
| page_reference |
A reference to a page on the online store. This is a special Shopify Global Id(Gid). Example: “gid://shopify/OnlineStorePage/1” |
| product_reference |
A reference to a product on the online store. This can only be used in Product mappings. Field: Use the Key value in Perfion or a Shopify Global Id(Gid).
RelatedProduct: Use the Related Product functionality in the Ecommerce API. See RelatedProduct for more information. |
| variant_reference |
A reference to a product variant on the online store. This is a special Shopify Global Id(Gid). Example: “gid://shopify/ProductVariant/1” |
|
file_reference file_reference_image |
A reference to a file on the online store. The file_reference can be mapped as a Field or a Attachment(Url) on Products and Variants. The Shopify Global Id(Gid) is translatable. Field: Use an Url or a Shopify Global Id(Gid).
Attachment(Url): Use a Perion File feature to upload files stored in Perfion. The file_reference as attachment is not translatable. files in file_reference will be created as file type GenericFile and files in file_reference_image will be created as file type MediaImage in Shopify content. |
| collection_reference |
A reference to a collection on the online store. This can only be used in Category mappings. Field: Use the Key value in Perfion or a Shopify Global Id(Gid).
RelatedCategory: The RelatedCategory is not supported for collection_reference. |
List types
List metafields enable you to store multiple values in a single metafield by using a Multi Feature in Perfion. The maximum number of values that can be stored in a metafield list is 128. The following types support Shopify List type by alling “list.” in the start og the type like “list.single_line_text_field”:
- list.color
- list.date
- list.date_time
- list.dimension
- list.file_reference
- list.metaobject_reference
- list.number_decimal
- list.number_integer
- list.page_reference
- list.product_reference
- list.rating
- list.single_line_text_field
- list.url
- list.variant_reference
- list.volume
- list.weight
- list.collection_reference
Use Case: Linking Related Products from Perfion to Shopify
Scenario:
A Shopify merchant wants to display related products on a product page - such as accessories or complementary items. These related products are already defined in Perfion.
Incorrect Setup Attempt:
The partner tried to map the related product using OutputKind = "Field", which only pulls raw data (e.g., a product name or ID) and doesn’t establish a true product relationship in Shopify.
Correct Setup:
To properly link another product as a reference, the mapping in Perfion should use OutputKind = "RelatedProduct":
This tells Perfion to treat the reference as a linked product, not just a field value. Shopify then recognizes it as a product relationship, allowing it to display the referenced item with full product details (image, price, link, etc.).
Comments
0 comments
Please sign in to leave a comment.