Data Mapping


#Native fields

The mapping section will let you map all necessary fields to match your BigCommerce data with your PIM source data.

It means that App will populate the data from the chosen PIM's attribute into BigCommerce target field (e.g. in the PIM, you use the "My_short_description" attribute to fill in the description of your products, then you will map it with the "Description" field in your BigCommerce instance).

They are two main types of functional limitations that are applied to the fields that you are going to map:

  • Attribute type used (visible in BigCommerce Platform Limits and listed on the mapping page under each attribute.
  • For some fields, the characters max length is established from the BigCommerce side and therefore it needs to be respected.

The drop-down list will be automatically populated with data from your PIM.

#Custom fields

Custom fields allow you to map almost any type of attribute that can be transformed into text from the Akeneo PIM into BigCommerce store. The list of available attributes is automatically prepopulated from the PIM.


  • Up to 200 custom fields can be selected in the Apps.
  • Only 1000 eligible attributes are displayed in the App ready to be selected.
  • Selected attributes value cannot be longer than 250 characters, otherwise it will not be imported.

Consult Custom fields mapping section to understand how to map Custom fields.

#Different types of mapping for BigCommerce native fields

Akeneo App for BigCommerce allows you to manage your mapping in two different ways:

  • Simple mapping - if your data modelization in the PIM is based on the same attributes for all PIM families then you can map one particular data source to match all your products (eg. If you use the "My_short_description" field to fill in your description for all of your products independently on their family, then you will map it using simple mapping.

  • Complex mapping - this option allows you to map a BigCommerce target field differently for each product family. See more details in the "Complex mapping" section.

Be aware that you can combine both types of mapping depending on your needs. If you wish to use the complex mapping for a specific field, all you need to do is to check the corresponding checkbox and click on "MANAGE FAMILY MAPPING" CTA to access complex mapping for this specific field.


Be careful if you opt for a complex mapping for one of the mandatory fields: make sure that your mapping is completed for all concerned families before launching your first import in order to avoid unnecessary errors.

You need to click on the SAVE button in the top right corner of the page to save the changes.

#Simple mapping for native fields

PIM connection settings For a moment, the following native target fields are available for mapping:

#Native fields for simple products & product models

    • Product Name* - cannot be empty as it acts as the product identifier
    • Default Price* - cannot be empty nor negative
    • Product Type* - if empty field, then the product type will be settled "physical" by default during import
    • Weight* - cannot be empty nor negative
    • Brand
    • Description
    • Images for simple products and product models - image attributes and asset collections
    • SKU
    • Product UPC/EAN
    • GTIN
    • Height
    • Width
    • Depth *Mandatory fields

#Native fields for product variants

  • SKU*
  • Default Price
  • Weight
  • Width
  • Height
  • Depth
  • GTIN
  • Variant image (1 image per variant)

*Mandatory fields

By default, product model attribute values are considered when creating product variants. It means that product variants created without a specific mapping will automatically use the configuration of the product model. If you wish to override certain product model information, use this section to map them (this does not apply to images)

#Media mapping

Media mapping allows you to map PIM images or PIM asset collections to BigCommerce images. By choosing PIM images, you will map & synchronize PIM image attributes to BigCommerce. If you select PIM asset collections, you will map and synchronize a specific asset attribute from the related asset family to the asset collection to BigCommerce.

The App allows you to map asset attributes of two types: media link or media file. Only asset attributes whose media type is image are selectable. If the asset attribute you want to map does not appear, please check the asset family settings to make sure it belongs to the right type.

#How to map media

Follow the following steps to map your custom fields:

  • In the Native fields tab, click on EDIT MEDIA MAPPING Edit media mapping
  • Now, choose a media source. You can choose between images and asset collections. Media source

It is not possible to map a mix of images and assets collections.

Image attributes

  • You can now select an image attribute that you want to map. Image attributes mapping

The App supports up to 15 images per product. Please note that it is only possible to map 1 image per variant.

Asset collections

  • You can now select an asset collection that you want to map. Then, select the asset attribute in the asset family related to your asset collection that you want to import. Asset collections mapping

The App supports up to 5 asset collections to synchronize and map 1 asset attribute for each asset collection at product level. This corresponds to a maximum of 250 images per product. Please note that it is only possible to map 1 asset collection at variant level.

  • Click on Save to save the mapping.

Please note that it is possible to change the order of your media. To do this, simply select your media - click on the icon with three stripes - and drag the asset to the desired position.

#Mapping - General Rules

They are four mandatory fields required for product creation on the BigCommerce API side:


  • Product Name*
  • Default Price*
  • Product Type*
  • Weight*


  • SKU* - BigCommerce API limitation

Default Price exception - If you use a system other than PIM for your price management, please set up your product price in PIM to 0 to avoid problems with product creation during import. Product default price field cannot be empty nor negative.

When you create product variants, make sure to set up a default price of the product model. Otherwise, the product model and its variants will not be created.

It is important to remember that if you set up your price to 0, you have to be aware that you need to change it before your Product goes to the production process. BigCommerce proposes the solution to set up a dynamic price by using their customized options; however, a price has to be set up on the PIM side to create your products and product variants correctly.

Weight exception - If some or most of your products are digital, please set up your Weight to 0 in PIM to avoid problems with product creation during import.

Be aware that BigCommerce uses the "NAME" value as the single product identifier. Therefore you cannot import two identic names into your BigCommerce store. You are able to modify the name of your products as many times as you want, but please always make sure not to create any doubles.

Please be aware that those exceptions are linked to BigCommerce API restrictions and, therefore, mandatory to import your product catalog correctly.

To review all BigCommerce API product catalog limits, please visit: BigCommerce Help Center

#Product models & Product variants

Please note that because of the BigCommerce product options structure, the mandatory fields for creating your product model need to be filled in the common part of the product models, even though you will then want to map a specific weight or price for your product variant. Without mandatory fields, product model will not be created and the connector will show an error during importation.

Those fields are:

  • Product model name
  • Weight
  • Price

You can map specific fields for your product model and then override that information via App for product variants.

Be aware that App does not manage the deletion of product models and product variants. If you have deleted a product model in your BigCommerce store, make sure to do it accordingly in your PIM before relaunching the import.

The App supports following PIM attribute types for product variants:

  • Simple Select
  • Metrics
  • Boolean

Images vs variants

  • Images for product models - once imported, if removed or modified in the PIM, changes will apply
  • Images for product variants, once imported, only modifications in the PIM will be taken into account, product variant image cannot be removed
  • Images attributed localted on the the product model level can be used on the product variant level
  • Image attribute localted on the product variant level cannot be used on the product model level

#Complex mapping for native fields

Please note that complex mapping is only available for simple products & product models.

Complex mapping allows you to map BigCommerce target fields differently for each product family. Depending on your data modelization strategy, it can be used for each target field or only for one or a few of them.

If you wish to use a complex mapping for one of the BigCommerce target fields, please check the box below the drop-down list. Then you will see the "MANAGE FAMILY MAPPING" CTA appear.

To define your family by family mapping, please click on the "MANAGE FAMILY MAPPING" CTA.

The additional family by family mapping section will appear.

Complex mapping section

All PIM families will be retrieved from your PIM and displayed in the PIM family column.

Same as for the Simple mapping (see above), PIM attributes will be prepopulated for each dropdown list. The attribute type allowed does vary and depends on the BigCommerce target value (see general mapping page).

On the top of the page, you will see the progression bar of your Family by Family mapping.

Please keep in mind that to avoid any errors during your import, if you decide on the Family to Family mapping for the mandatory values, you should complete your mapping for all concerned families before launching your first import.

#Custom fields mapping

Thanks to custom fields you can map following attributes types from your Akeneo PIM into BigCommerce:

  • Date (format: MM/DD/YYYY)
  • Identifier
  • Multi-select
  • Simple select
  • Measurement
  • Number
  • Price
  • Text
  • Text area (up to 250 characters)
  • Boolean
  • Those listed attribute types will be transformed into text.
  • The translated title of your attribute will be imported as the attribute name.
  • If the selected attribute exists only for some of your families, only those families will be enriched with this specific custom field.
  • The App does not impact the import order of custom fields in the BigCommerce.
  • If you delete product attributes in your PIM or in the App interface, those will be removed automatically from your product page in the BigCommerce during the next import.
  • If you changed some attribute translations/labels in your PIM, please make sure to run a FULL import to update your product pages in your BigCommerce store correctly. Otherwise, new translations will be missing.

Follow the following steps to map your custom fields:

  1. Go to: Custom fields tab >> Click on Manage Custom fields Custom fields manage
  2. Select PIM attributes that you want to map Custom fields select
  3. Validate your choice by clicking on Confirm selection Custom fields confirm

Follow the following steps to remove some of the custom fields from the mapping:

  1. Go to: Custom fields tab >> Click on Manage Custom fields Custom fields manage
  2. Deselect PIM attributes that you want to remove from your mapping
  3. Validate your choice by clicking on Confirm selection

Learn more! Take a look at these related sections: