[NEW] Reference entity mapping

Summary

New feature

The Shopify app now allows you to sync your reference entities as metaobjects. This lets you use them as variation options and create swatches or to enrich your product pages with structured content.

 

Reference entity mapping

This section explains how to configure and map Akeneo reference entities to Shopify metaobjects in the Akeneo App for Shopify.

 

Reference entity

A reference entity in Akeneo is used to manage structured, reusable product information such as colors, fabrics, or ingredients. These entities have their own attributes and lifecycle, and can be linked to products or other reference entities. This allows you to enrich your catalog with detailed content like text or images, which can be reused across products.

The app allows you to map and sync up to 10 reference entities to existing Shopify metaobjects. This enables you to display richer content on your Shopify storefront, such as color swatches, brands, or ingredient lists.

Note: The app does not create Shopify metaobjects or metafield definitions. These must be created manually in Shopify before mapping.

 

 

Supported attribute types

Reference entity attribute Supported? Compatible fields in Shopify
Text Yes
  • Single line text metafield (one value)
  • Multi-line text metafield
  • Color metafield (one value/list of values) - list of values must be separated by a comma
Simple option Yes
  • Single line text metafield (one value/list of values)
Multiple options No  
Asset collections Yes
  • File metafield (one file/list of files)
Number No  
Reference entity single link No  
Reference entity multiple links No  
Image No  

Please note that this is the initial version of the feature.
If you require support for additional attributes, you can submit a feature request via this link.

 

 

Prepare your mapping

Step 1: Shopify configuration

To map reference entities, start by manually creating the necessary definitions in Shopify.

Create a metaobject definition

  1. In Shopify admin, go to Settings > Custom data > Metaobject definitions.
  2. Click Add definition, give it a name, and add fields based on the supported attribute types.
  3. Save your definition.

We recommend keeping the ‘Active-draft status’ option disabled to ensure your metaobject entries are set to active by default.
If you enable this option, all entries will instead be created in draft status automatically.

 

Create a metaobject metafield definition

  1. In Shopify admin, go to Settings > Custom data > Metafield definitions, choose Product or Variant.
  2. Click Add definition and select Metaobject reference as the field type.
  3. Choose either one value or list of values depending on your reference entity usage.
  4. Save the metafield definition.

If you want to use the reference entity as a variation axis, the metafield must:

  • Be created at the product level
  • Be defined as a list of values
 

 

Step 2: Get metaobject and metafield technical details

Once the definitions are created, the next step is to retrieve the necessary Shopify data for mapping in the app.
This data will be required in Step 4 to map your reference entities using JSON.

Get metaobject details

  1. In the app, go to Metaobject > Click on Help for configuration under the Metaobjects – PIM Reference entities section.
  2. Go to the Metaobject definition tab > Select the metaobject you want to map.
  3. Copy the following details for each field you want to map:
    • Metaobject GID
    • shopify_metaobject_field_key
    • shopify_metaobject_field_type
    • required

Get metaobject metafield details

  1. In the app, go to Metaobject > Click on Help for configuration under the Metaobjects – PIM Reference entities section.
  2. Go to the Product metafield definition or Variant metafield definition  tab > Copy the Metafield GID of each metafield you want to map.

In your JSON mapping, use:

  • shopify_product_definition_id if the metafield definition is at the product level
  • shopify_variant_definition_id if the metafield is at the variant level
 

 

Step 3: Get Akeneo reference entity technical details

You can now retrieve the necessary Akeneo data for mapping in the app.
This data will be required in Step 4 to map your reference entities using JSON.

Get reference entity code (pim_resource_id)

  1. In Akeneo, go to Entities > [your reference entity] > Properties.
  2. Copy the code.

Get reference entity attribute code and type (pim_attribute_code and type in fields )

  1. In Akeneo, go to Entities > [your reference entity] > Attributes.
  2. Copy the attribute code and check its type.

Get reference entity attribute code (pim_attribute_code in metafield_attributes)

  1. In Akeneo, go to Entities > [your reference entity] > Attributes.
  2. Copy the attribute code and check its type.

Get asset family code (asset_family_code)

  1. In Akeneo, go to Assets > [your asset family] > Edit family > Properties.
  2. Copy the code.

Get asset attribute code (asset_attribute_media_code and asset_attribute_alt_text_code)

  1. In Akeneo, go to Settings > Attributes > [your attribute] > Properties.
  2. Copy the code.

 

Step 4: Map your reference entities

Use the following JSON template to configure your app mapping.
This template includes an example of the format to follow for each supported attribute type.

JSON mapping template

[
    {
      "scope": "reference_entity",
      "type": "reference_entity",
      "pim_resource_id": "",
      "shopify_metaobject_definition_id": "gid://shopify/MetaobjectDefinition/00000000000",
      "fields": [
        {
          "type": "",
          "pim_attribute_code": "",
          "shopify_metaobject_field_type": "",
          "shopify_metaobject_field_key": "",
          "required": ,
          "use_as_list_of_values": 
        },
        {
          "type": "",
          "pim_attribute_code": "",
          "shopify_metaobject_field_type": "",
          "shopify_metaobject_field_key": "",
          "required": ,
          "use_as_list_of_values": 
        },      
        {
            "type": "",
            "pim_attribute_code": "",
            "shopify_metaobject_field_type": "",
            "shopify_metaobject_field_key": "",
            "required": ,
            "use_as_list_of_values": ,
            "asset_family_code": "",
            "asset_attribute_media_code": "",
            "asset_attribute_alt_text_code": ""
        }
      ],
      "use_as_variation_axis": ,
      "metafield_attributes": [
        {
          "pim_attribute_code": "",
          "shopify_product_definition_id": "gid://shopify/MetafieldDefinition/000000000",
          "shopify_variant_definition_id": "gid://shopify/MetafieldDefinition/000000000"
        }
      ]
    }
  ]
 
 

JSON mapping example

[
    {
      "scope": "reference_entity",
      "type": "reference_entity",
      "pim_resource_id": "color",
      "shopify_metaobject_definition_id": "gid://shopify/MetaobjectDefinition/1234567890",
      "fields": [
        {
          "type": "text",
          "pim_attribute_code": "label",
          "shopify_metaobject_field_type": "single_line_text_field",
          "shopify_metaobject_field_key": "label",
          "required": false,
          "use_as_list_of_values": false
        },
        {
          "type": "text",
          "pim_attribute_code": "color_hex_code",
          "shopify_metaobject_field_type": "color",
          "shopify_metaobject_field_key": "hex_code",
          "required": false,
          "use_as_list_of_values": true
        },
        {
          "type": "text",
          "pim_attribute_code": "Base_color",
          "shopify_metaobject_field_type": "single_line_text_field",
          "shopify_metaobject_field_key": "base_color",
          "required": true,
          "use_as_list_of_values": true
        },     
        {
            "type": "asset_collection",
            "pim_attribute_code": "color_image",
            "shopify_metaobject_field_type": "file_reference",
            "shopify_metaobject_field_key": "image",
            "required": false,
            "use_as_list_of_values": false,
            "asset_family_code": "color_assets",
            "asset_attribute_media_code": "media",
            "asset_attribute_alt_text_code": "alt-text"
        }
      ],
      "use_as_variation_axis": true,
      "metafield_attributes": [
        {
          "pim_attribute_code": "shoe_color",
          "shopify_product_definition_id": "gid://shopify/MetafieldDefinition/12334567",
          "shopify_variant_definition_id": null
        },
        {
          "pim_attribute_code": "clothing_color",
          "shopify_product_definition_id": "gid://shopify/MetafieldDefinition/33456789",
          "shopify_variant_definition_id": null
        }
      ]
    },
{
      "scope": "reference_entity",
      "type": "reference_entity",
      "pim_resource_id": "size",
      "shopify_metaobject_definition_id": "gid://shopify/MetaobjectDefinition/2345678901",
      "fields": [
        {
          "type": "text",
          "pim_attribute_code": "label",
          "shopify_metaobject_field_type": "single_line_text_field",
          "shopify_metaobject_field_key": "label",
          "required": false,
          "use_as_list_of_values": false
        }
      ],
      "use_as_variation_axis": false,
      "metafield_attributes": [
        {
          "pim_attribute_code": "size",
          "shopify_product_definition_id": "gid://shopify/MetafieldDefinition/333445566",
          "shopify_variant_definition_id": "gid://shopify/MetafieldDefinition/444556677"
        }
      ]
    },
    {
      "scope": "reference_entity",
      "type": "reference_entity",
      "pim_resource_id": "brands",
      "shopify_metaobject_definition_id": "gid://shopify/MetaobjectDefinition/3456789012",
      "fields": [
        {
          "type": "text",
          "pim_attribute_code": "label",
          "shopify_metaobject_field_type": "single_line_text_field",
          "shopify_metaobject_field_key": "label",
          "required": false,
          "use_as_list_of_values": false
        },   
        {
            "type": "asset_collection",
            "pim_attribute_code": "brand_logo",
            "shopify_metaobject_field_type": "file_reference",
            "shopify_metaobject_field_key": "image",
            "required": false,
            "use_as_list_of_values": false,
            "asset_family_code": "brand_assets",
            "asset_attribute_media_code": "image_resized",
            "asset_attribute_alt_text_code": null
        }
      ],
      "use_as_variation_axis": false,
      "metafield_attributes": [
        {
          "pim_attribute_code": "brands",
          "shopify_product_definition_id": "gid://shopify/MetafieldDefinition/45556677",
          "shopify_variant_definition_id": null
        }
      ]
    }
  ]
 
 

 

Field descriptions

Field Description Value
GLOBAL STRUCTURE
scope Static value. reference_entity
type Static value. reference_entity
pim_resource_id Code of the reference entity in Akeneo.  
shopify_metaobject_definition_id Shopify GID of the metaobject definition.  
REFERENCE ENTITY ATTRIBUTE MAPPING
fields Section containing the list of metaobject fields to be mapped between Akeneo and Shopify.  
type Attribute type in Akeneo. text, single_option, asset_collection
pim_attribute_code Akeneo reference entity attribute code.  
shopify_metaobject_field_type Shopify field type.  
shopify_metaobject_field_key Shopify field key. 

If the field type starts with list., make sure to remove the list. prefix and set the use_as_list_of_values field to true.		  
required Whether the field is required in Shopify. true, false
use_as_list_of_values Set to true if the Shopify field expects a list. true, false
asset_family_code (for asset collections) Akeneo asset family code in Akeneo.  
asset_attribute_media_code (for asset collections) Akeneo media attribute code.  
asset_attribute_alt_text_code  (for asset collections) Akeneo alt-text attribute code. This value can be null.
VARIATION AXIS & PRODUCT/VARIANT ATTRIBUTE MAPPING
use_as_variation_axis Set to true to use the metaobject as a variant option.
Set to false to use the simple option as a variant option.		 true, false
metafield_attributes Section containing the list of Akeneo attributes  to be mapped with Shopify metafields  
pim_attribute_code Code of the PIM attribute (reference entity single link or reference entity multiple links) related to the reference entity.  
shopify_product_definition_id Shopify GID of the product metafield definition (metaobject_reference) related to the metaobject. This value can be null.
shopify_variant_definition_id Shopify GID of the variant metafield definition  (metaobject_reference) related to the metaobject. This value can be null.

 

Field examples

PIM attribute type Shopify field type Example
Text Single line text - one value 
       {
          "type": "text",
          "pim_attribute_code": "label",
          "shopify_metaobject_field_type": "single_line_text_field",
          "shopify_metaobject_field_key": "label",
          "required": false,
          "use_as_list_of_values": false
        }
Single line text - list of values 
       {
          "type": "text",
          "pim_attribute_code": "Base_color",
          "shopify_metaobject_field_type": "single_line_text_field",
          "shopify_metaobject_field_key": "base_color",
          "required": false,
          "use_as_list_of_values": true
        }
Multi line text 
        {
          "type": "text",
          "pim_attribute_code": "description",
          "shopify_metaobject_field_type": "multi_line_text_field",
          "shopify_metaobject_field_key": "description",
          "required": false,
          "use_as_list_of_values": false
        }
Color 
       {
          "type": "text",
          "pim_attribute_code": "color_hex",
          "shopify_metaobject_field_type": "color",
          "shopify_metaobject_field_key": "color",
          "required": false,
          "use_as_list_of_values": true
        }
Single option Single line text - one value 
      	{
          "type": "single_option",
          "pim_attribute_code": "base_pattern",
          "shopify_metaobject_field_type": "single_line_text_field",
          "shopify_metaobject_field_key": "base_pattern",
          "required": true
          "use_as_list_of_values": false
      	}
Single line text - list of values 
      	{
          "type": "single_option",
          "pim_attribute_code": "base_color",
          "shopify_metaobject_field_type": "single_line_text_field",
          "shopify_metaobject_field_key": "base_color",
          "required": true
          "use_as_list_of_values": false
      	}
Asset collection File - one value 
        {
            "type": "asset_collection",
            "pim_attribute_code": "test_asset_collection",
            "shopify_metaobject_field_type": "file_reference",
            "shopify_metaobject_field_key": "image_one_file",
            "required": false,
            "use_as_list_of_values": false,
            "asset_family_code": "my_asset_family",
            "asset_attribute_media_code": "media",
            "asset_attribute_alt_text_code": "label"
        }
File - list of values 
        {
            "type": "asset_collection",
            "pim_attribute_code": "test_asset_collection",
            "shopify_metaobject_field_type": "file_reference",
            "shopify_metaobject_field_key": "image_list_of_files",
            "required": false,
            "use_as_list_of_values": true,
            "asset_family_code": "my_asset_family",
            "asset_attribute_media_code": "media",
            "asset_attribute_alt_text_code": "label"
        }

 

Map your reference entities

  1. In the app, go to Metaobject > Copy/paste your JSON mapping.
  2. Save your mapping.

Unmap your reference entities

  1. In the app, go to Metaobject > delete all your JSON mapping or just attributes you want to remove.
  2. Save your mapping.

Want to find out more? Take a look at these related articles