Reference entity mapping

Summary

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.

When creating file type fields in your metaobject, please select the "Accept all file types" option. The "Accept specific file types" option is not currently supported by the app.

 

 

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: Retrieve 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.

Install the Shopify GraphiQL App

  1. Visit the GraphiQL app installation page.
  2. Enter your store URL and select read access for metaobject_definitions and products.
  3. Install the app and open it from your Shopify admin.
  4. You can now access this app from your Shopify store.

 

Retrieve metaobject details

Run this query in the GraphiQL app:

Get metaobject query

query GetMetaObjectDefinitions {
  metaobjectDefinitions(first: 20) {
    edges {
      node {
        id
        name
        metaobjectsCount
        fieldDefinitions {
          name
          description
          key
          type {
            name
          }
          validations {
            name
            type
            value
          }
        }
      }
    }
  }
 
 

This API request returns a payload containing data about a metaobject definition. 

Below are the key fields you should retrieve from the payload, along with their corresponding mapping fields:

API field Description JSON mapping field
Node
id This field refers to the GID of the metaobject definition. shopify_metaobject_definition_id
Field Definitions
Key This field refers to the unique key of the metaobject field. shopify_metaobject_field_key
Type    
name This field refers to the name of the field's type. shopify_metaobject_field_type

 

Payload example

{
          "node": {
            "id": "gid://shopify/MetaobjectDefinition/1234567890",
            "type": "color",
            "name": "Color",
            "metaobjectsCount": 5,

            "fieldDefinitions": [
              {
                "name": "Label",
                "description": "",
                "key": "label",
                "type": {
                  "name": "single_line_text_field",

                },
                "validations": []
              },
              
                },
                "validations": []
              }
            ]
          }
        },
 
 

 

Retrieve metaobject metafield details

Run this query in the GraphiQL app:

Get metafield query

{
  metafieldDefinitions(ownerType: PRODUCT, first: 250) {
    edges {
      node {
        id
        name
        namespace
        key
        type {
          name
        }
      }
    }
  }
}

Please note that you must adjust the ownerType based on the level of the metafield definition you want to retrieve: PRODUCT or PRODUCTVARIANT.

 
 
 

This API request returns a payload containing data about all metafield definition. Look for metafields with type 'metaobject_reference'.

Below are the key fields you should retrieve from the payload, along with their corresponding mapping fields:

API field Description JSON mapping field
Node
id This field refers to the GID of the metafield definition. shopify_product_definition_id or shopify_variant_definition_id

 

Payload example

{
  "data": {
    "metafieldDefinitions": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/MetafieldDefinition/0000000000",
            "name": "Color swatch",
            "namespace": "custom",
            "key": "Color_swatch",
            "type": {
              "name": "metaobject_reference"
            }
          }
        }
      ]
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 24,
      "actualQueryCost": 8,
      "throttleStatus": {
        "maximumAvailable": 2000,
        "currentlyAvailable": 1992,
        "restoreRate": 100
      }
    }
  }
 
 

 

Step 3: Retrieve Akeneo reference entity technical details

Retrieve reference entity code (pim_resource_id)

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

Retrieve 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.

Retrieve 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.

Retrieve asset family code (asset_family_code)

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

Retrieve 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