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.

Native fields are mapped in the following tabs of the app: Products for simple products, Products with variants for product models and their variants, and Combined Listings for combined listing parents (only displayed when this product model structure is selected).

What happens when the PIM value is empty

When a mapped Attribute has no value in the PIM for a product, the app behaves as follows. A native field that is not mapped is never modified by the app.

Native fields Behavior in Shopify when the PIM value is empty
Title The product is rejected by Shopify with the error "Title can't be blank". For combined listing parents, the root product model code is used instead.
Description, Category, Page title, Meta description, URL handle, Product type, Vendor, Tags The value already in Shopify is kept.
Price, Cost per item, Weight, Country/Region of origin The value already in Shopify is kept.
Compare at Price The compare-at price is removed in Shopify.
SKU, Barcode, HS code The value is cleared in Shopify.
Track quantity Set to No: the quantity is not tracked.
Continue selling when out of stock Set to No: the product cannot be sold when it is out of stock.
Taxable Set to Yes.
Physical Set to Yes.

A value of 0 is not considered empty: it is sent to Shopify as is (for example, a compare-at price of 0 is saved as 0.00).

List of native fields

Native fields for simple products

Native fields Supported? Compatible 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: 

• 30 image attributes max 
• 5 asset collections max. An extended limit of 50 is available as an option: it is disabled by default and can be enabled on request to our support team.
The same asset collection can be mapped several times, each time with a different asset attribute - media.

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.

An empty value in the PIM does not clear the price in Shopify: the last synchronized price is kept. A value of 0 is saved as 0.00.
Compare at Price

Yes

 Attributes: Number, Price If the PIM value is empty, the compare-at price is removed in Shopify.
A value of 0 is saved as 0.00 in Shopify.
If the field is not mapped, the app never modifies the compare-at 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 sent on every synchronization when it is not empty in the PIM.

Changing the value in the PIM changes the product URL in Shopify. To preserve existing links and SEO, create the corresponding URL redirects in Shopify.

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 four 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

By default, the app performs a "set" operation on tags and pushes all tags on every synchronization, which can potentially overwrite tags that were added outside our app on Shopify.

To avoid this, our team can enable the tag preservation mode on your store. In this mode, the tags are set when the product is created. On updates, the app adds the PIM tags and removes only the tags it synchronized before and that the PIM no longer sends. Tags added directly in Shopify, by a user or by another app, are kept. Tags synchronized before this mode was enabled are not removed.

To request this, please contact our support team via this link.

Native fields for product models

Native fields Supported? 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: 

• 30 image attributes max 
• 5 asset collections max. An extended limit of 50 is available as an option: it is disabled by default and can be enabled on request to our support team.
The same asset collection can be mapped several times, each time with a different asset attribute - media.

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 sent on every synchronization when it is not empty in the PIM.

Changing the value in the PIM changes the product URL in Shopify. To preserve existing links and SEO, create the corresponding URL redirects in Shopify.

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 four 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

By default, the app performs a "set" operation on tags and pushes all tags on every synchronization, which can potentially overwrite tags that were added outside our app on Shopify.

To avoid this, our team can enable the tag preservation mode on your store. In this mode, the tags are set when the product is created. On updates, the app adds the PIM tags and removes only the tags it synchronized before and that the PIM no longer sends. Tags added directly in Shopify, by a user or by another app, are kept. Tags synchronized before this mode was enabled are not removed.

To request this, please contact our support team via this link.

Native fields for product variants

Native fields Supported? Compatible PIM attributes & properties Limitations
MEDIA      
Images, videos, 3D models

Yes

 Attribute: Image, Asset collection

The limitation depends on the media source:

• 2 image attributes max 
• 2 asset collections 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.

An empty value in the PIM does not clear the price in Shopify: the last synchronized price is kept. A value of 0 is saved as 0.00.
Compare at Price

Yes

 Attributes: Number, Price If the PIM value is empty, the compare-at price is removed in Shopify.
A value of 0 is saved as 0.00 in Shopify.
If the field is not mapped, the app never modifies the compare-at 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.

Native fields for combined listing parents

When the Split PIM product models using Combined Listings product model structure is selected, the fields of the combined listing parent product are mapped in the Combined Listings tab of the app. Their values come from the root product model in Akeneo. More information about this structure is available here.

Native fields Supported? Supported PIM attributes & properties Limitations
BASIC INFORMATION      
Title

Yes

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

If not mapped, or if the value is empty on the root product model, the root product model code is used as the title.

If no field is mapped for the parent product, the parent is created once and not updated by the app afterwards, so you can edit it directly in Shopify.
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 Media are mapped in the Combined Listings tab. Automatic generation of the media mapping is not available for the parent product.

The limitation depends on the media source: 

• 30 image attributes max 
• 5 asset collections max. An extended limit of 50 is available as an option: it is disabled by default and can be enabled on request to our support team.
The same asset collection can be mapped several times, each time with a different asset attribute - media.

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 sent on every synchronization when it is not empty in the PIM.

Changing the value in the PIM changes the product URL in Shopify. To preserve existing links and SEO, create the corresponding URL redirects in Shopify.
STATUS      
Status

Yes

 Attribute: Simple select

There are four 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 parent product is created with the ACTIVE status.
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

By default, the app performs a "set" operation on tags and pushes all tags on every synchronization, which can potentially overwrite tags that were added outside our app on Shopify.

To avoid this, our team can enable the tag preservation mode on your store. In this mode, the tags are set when the product is created. On updates, the app adds the PIM tags and removes only the tags it synchronized before and that the PIM no longer sends. Tags added directly in Shopify, by a user or by another app, are kept. Tags synchronized before this mode was enabled are not removed.

To request this, please contact our support team via this link.

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