Native field mapping

Summary

Native field mapping

This section provides an overview of native field mapping in the Akeneo App for Shopify.

Native Fields

A native field refers to a predefined and built-in attribute or data field that is available within the platform's standard functionality. These fields are provided by default and are designed to store specific types of information related to products, orders, customers, and other elements of an e-commerce store.

Native fields in Shopify are ready to use without any additional customization or development work. They are integral to the core features and capabilities of the platform, enabling merchants to effectively manage their online stores.

These fields are designed to capture essential information about products, facilitate organization and searchability, enable inventory management, support marketing efforts, and enhance the overall customer experience.

Mapping

Mapping refers to the process of establishing a connection between corresponding data fields in Akeneo and Shopify. Mapping is essential to ensure that product data is correctly synchronized between the two platforms. The process involves associating Akeneo attributes with the corresponding Shopify fields.

Please note that the app does not allow you to pass null values on synchronized attributes. This means that an attribute value synchronized in Shopify and then cleared in PIM cannot be cleared in Shopify.

 

List of Native fields

Native fields for simple products

Native fields   Supported PIM attributes Limitations
BASIC INFORMATION      
Title - mandatory field

Yes

 Attributes: Identifier, Text
Properties: Identifier (UUID), Family, Parent, Root parent		 255 characters max
Description

Yes

 Attributes: Text area, Text
Properties: Identifier (UUID), Family, Parent, Root parent		 512 KB max size
Category Yes Attribute: Reference entity single link

The reference entity must include a GID attribute, and its value must correspond to a valid Shopify category ID. 

To assign a Shopify taxonomy category, you need to follow these steps in the PIM:

  1. Create a reference entity dedicated to Shopify categories and add a text attribute with the code “gid”.
  2. Create the entries in this reference entity. Each entry represents a Shopify category and the full category ID must be stored in the GID attribute (code "gid"). Example: gid://shopify/TaxonomyCategory/aa-1-20-23. You will find the full product taxonomy here:
  1. Create a product attribute of type reference entity single link and link it to the category reference entity.
  2. Assign the relevant category to each product.
MEDIA      
Images, videos, 3D models

Yes

 Attribute: Image, Asset collection The limitation depends on the media source: 

• 15 image attributes max 
• 5 asset collections max

List of supported extensions available here.
Alt texts

Yes

 Attribute: Asset attribute - Text 512 characters max
PRICING      
Price

Yes

 Attributes: Number, Price Values cannot be negative
Compare at Price

Yes

 Attributes: Number, Price  
Taxable

Yes

 Attributes: Yes/No
Property: Enabled		  
Cost per item

Yes

 Attributes: Number, Price Values cannot be negative
Unit price - Total measure

No

    
Unit price - Base measure

No

    
INVENTORY      
SKU

Yes

 Attributes: Identifier, Text
Properties: Identifier (UUID), Family, Parent, Root parent		 255 characters max
Barcode

Yes

 Attributes: Identifier, Text
Properties: Identifier (UUID), Family, Parent, Root parent		 255 characters max
Track quantity

Yes

 Attribute: Yes/No
Property: Enabled		 By default, the quantity is not tracked.

• Yes: track quantity
• No/null: do not track quantity
Continue selling when out of stock

Yes

 Attribute: Yes/No
Property: Enabled		  
SHIPPING      
Physical

Yes

 Attribute: Yes/No
Property: Enabled		  
HS code

Yes

 Attributes: Identifier, Text
Properties: Identifier (UUID), Family, Parent, Root parent 		 between 6 and 13 digits
Weight

Yes

 Attributes: Measurement, Number 2 000 000 000 unit max

Note: The weight unit is the one configured by default in Shopify.
Country/Region of origin

Yes

 Attribute: Simple select
 		 The option label and code format must comply with ISO 3166-1 alpha-2 guidelines.

Please note that only country codes are supported, not region codes.
SEARCH ENGINE LISTING      
Page title

Yes

 Attribute: Text
Properties: Identifier (UUID), Family, Parent, Root parent		 70 characters max
Meta description

Yes

 Attributes: Text area, Text
Properties: Identifier (UUID), Family, Parent, Root parent		 320 characters max
URL handle

Yes

 Attribute: Text
Properties: Identifier (UUID), Family, Parent, Root parent		 255 characters max
Value cannot contain spaces.
Value must be unique.
Value is only synchronized when creating product.

The value should only contain the product handle, not the full URL. 
If you provide the complete URL, Shopify will treat it as a handle (e.g. if you have "https://www.akeneo-shop/my-product" in the PIM, Shopify will convert it to the handle "https-www-akeneo-shop-my-product".
STATUS      
Status Yes Attribute: Simple select

There are three possible statuses (to use as option codes):

• ACTIVE
• DRAFT
• ARCHIVED

• UNLISTED

Note: You can set the option code in either lowercase or uppercase. The app will automatically convert it to uppercase to comply with Shopify’s requirements.

If not mapped, the status will be set by default depending on the PIM product status (see details here). 
You can also disable PIM product status synchronization by default to manage status directly from Shopify. To request deactivation, please contact support.
PRODUCT ORGANIZATION      
Product type

Yes

 Attributes: Text, Simple select
Properties: Identifier (UUID), Family, Parent, Root parent		 255 characters max
Vendor

Yes

 Attributes: Text, Simple select, Reference entity single link
Properties: Identifier (UUID), Family, Parent, Root parent		 255 characters max
Tags

Yes

 Attributes: Simple select, Multi select, Text, Text area
Properties: Identifier (UUID), Family, Categories, Parent, Root parent		 250 tags max

Native fields for product models

Native fields   Supported PIM attributes & properties Limitations
BASIC INFORMATION      
Title - mandatory field

Yes

 Attributes: Identifier, Text
Properties: Identifier (UUID), Family, Parent, Root parent		 255 characters max
Description

Yes

 Attributes: Text area, Text
Properties: Identifier (UUID), Family, Parent, Root parent		 512 KB max size
Category Yes Attribute: Reference entity single link

The reference entity must include a GID attribute, and its value must correspond to a valid Shopify category ID. 

To assign a Shopify taxonomy category, you need to follow these steps in the PIM:

  1. Create a reference entity dedicated to Shopify categories and add a text attribute with the code “gid”.
  2. Create the entries in this reference entity. Each entry represents a Shopify category and the full category ID must be stored in the GID attribute (code "gid"). Example: gid://shopify/TaxonomyCategory/aa-1-20-23. You will find the full product taxonomy here:
  1. Create a product attribute of type reference entity single link and link it to the category reference entity.
  2. Assign the relevant category to each product.
MEDIA      
Images, videos, 3D models

Yes

 Attribute: Image, Asset collection The limitation depends on the media source: 

• 15 image attributes max 
• 5 asset collections max

List of supported extensions available here.
Alt texts

Yes

 Attribute: Asset attribute - Text 512 characters max
SEARCH ENGINE LISTING      
Page title

Yes

 Attribute: Text
Properties: Identifier (UUID), Family, Parent, Root parent		 70 characters max
Meta description

Yes

 Attributes: Text area, Text
Properties: Identifier (UUID), Family, Parent, Root parent		 320 characters max
URL handle

Yes

 Attribute: Text
Properties: Identifier (UUID), Family, Parent, Root parent		 255 characters max
Value cannot contain spaces.
Value must be unique.
Value is only synchronized when creating product.

The value should only contain the product handle, not the full URL. 
If you provide the complete URL, Shopify will treat it as a handle (e.g. if you have "https://www.akeneo-shop/my-product" in the PIM, Shopify will convert it to the handle "https-www-akeneo-shop-my-product".
STATUS      
Status Yes Attribute: Simple select

There are three possible statuses:

• ACTIVE
• DRAFT
• ARCHIVED
• UNLISTED

Note: You can set the option code in either lowercase or uppercase. The app will automatically convert it to uppercase to comply with Shopify’s requirements.

If not mapped, the status will be set to ACTIVE by default (see details here). 
You can also disable PIM product status synchronization by default to manage status directly from Shopify. To request deactivation, please contact support.
Product type

Yes

 Attributes: Text, Simple select
Properties: Identifier (UUID), Family, Parent, Root parent		 255 characters max
Vendor

Yes

 Attributes: Text, Simple select, Reference entity single link
Properties: Identifier (UUID), Family, Parent, Root parent		 255 characters max
Tags

Yes

 Attributes: Simple select, Multi select, Text, Text area
Properties: Identifier (UUID), Family, Categories, Parent, Root parent		 250 tags max

Native fields for product variants

Native fields   Supported PIM attributes Limitations
MEDIA      
Images, videos, 3D models

Yes

 Attribute: Image, Asset collection

The limitation depends on the media source:

• 1 image attribute max 
• 1 asset collection max

You can map up to 2 image attributes or asset collections. The first one will be used by default, and the second will serve as a fallback if no image is found in the first.

List of supported extensions available here.
Alt texts

Yes

 Attribute: Asset attribute - Text 512 characters max
PRICING      
Price

Yes

 Attributes: Number, Price Values cannot be negative
Compare at Price

Yes

 Attributes: Number, Price  
Taxable

Yes

 Attributes: Yes/No
Property: Enabled		  
Cost per item

Yes

 Attributes: Number, Price Values cannot be negative
Unit price - Total measure

No

    
Unit price - Base measure

No

    
INVENTORY      
SKU

Yes

 Attributes: Identifier, Text
Properties: Identifier (UUID), Family, Parent, Root parent		 255 characters max
Barcode

Yes

 Attributes: Identifier, Text
Properties: Identifier (UUID), Family, Parent, Root parent		 255 characters max
Track quantity

Yes

 Attribute: Yes/No
Property: Enabled		 By default, the quantity is not tracked.

• Yes: track quantity
• No/null: do not track quantity
Continue selling when out of stock

Yes

 Attribute: Yes/No
Property: Enabled		  
SHIPPING      
Physical

Yes

 Attribute: Yes/No
Property: Enabled		  
HS code

Yes

 Attributes: Identifier, Text
Properties: Identifier (UUID), Family, Parent, Root parent 		 between 6 and 13 digits
Weight

Yes

 Attributes: Measurement, Number 2 000 000 000 unit max
Note: The weight unit is the one configured by default in Shopify.
Country/Region of origin

Yes

 Attribute: Simple select
 		 The option label and code format must comply with ISO 3166-1 alpha-2 guidelines.

Please note that only country codes are supported, not region codes.

Please be aware that the option code will be used as a fallback when there is no option label available on simple-select.
E.g. In a simple-select dropdown for selecting a country, if the "France" option does not have a label defined (e.g., no display name like "France" for users), the app will automatically display the country code "FR" as a fallback.

 

Please note that Akeneo properties can be mapped with native fields.

List of supported properties:

  • Identifier - UUID
  • Enabled - status
  • Family
  • Categories
  • Parent
  • Root parent
  • Created
  • Updated

Only property code will be synchronized - not labels.

 

 

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