How to configure catalogs for Apps?


If you require assistance in configuring your catalog to retrieve data effectively, please consult the provided documentation here.



What's a catalog?

With catalogs, you can configure which products you want to share with an app thanks to a product selection composed of one or several criteria that allow you to filter products.

When an app uses catalogs to retrieve product data, it automatically enables the Catalogs tab and creates catalogs for this app in your PIM. To configure your catalogs: 

  1. Go to Connect, then Connected Apps
  2. Click Manage app, and then click Catalogs.

Here you access the list of all the catalogs the app can manage with a label and a status.

Click on the catalog you want to set up to access the configuration interface.

When you access a catalog, you will see two tabs:

  • Product selection: where you will configure criteria to filter your product selection,
  • Filter the values: when a catalog is not compatible with mapping, we display this tab to allow you to choose which values to send to the app based on filters,
  • Product mapping: where you can map your PIM attributes with the app expected targets.
  • Settings: to get information about which locales and currencies your app manages for the current catalog


If you can't click on Manage apps, please read our paragraph Who can connect apps?



Configure your catalog product selection

In the Product selection tab, you can define selection criteria. They are the attributes or system fields you can use to filter your products. Altogether, the criteria will create your Product selection.

When there are no criteria, your whole PIM catalog is selected.



You will find the system fields at the top of the list, and below are all the attributes gathered by attribute groups. There is a search bar to help you find the attributes.

Each time you add a criterion, its color turns purple to inform you that it is already used.  
A new line appears in the product selection.

Let's see how a line is organized.

  1. You will find the system fields or attribute you chose in purple on the left.
  2. Then, you have to choose an operator. Depending on the filter, the operator list changes.

The following fields vary depending on your filter. There can be up to 3 types of fields.

  • You can have the value field. For example, if your filter is a multi-select attribute type, you can choose which options you want to filter on.
  • If your filter has a value per channel and/or per locale, the channel and locale fields appear to let you choose which locale/channel you want to filter on.

If you want to remove a condition, click on the cross at the end of the line.


Available conditions

To select your products, you can use the following system fields and attribute types of the PIM as conditions:

  • Status
  • Category
  • Completeness
  • Family
  • Simple select attribute
  • Text attribute
  • Measurement attribute
  • Yes/No attribute
  • Multi-select attribute
  • Number attribute
  • Text area attribute
  • Date attribute
  • Identifier
  • Measurement
  • Last Updated 


Configure the product data mapping

After configuring your product selection, you must configure your product data mapping. To do so, let's switch to the Mapping tab. 

You will see 2 columns in this tab: the target list and the Sources. The left panel displays all the app's targets to synchronize your product data, and you can configure the sources to map with the target in the right panel. 


Please note that target names are not translated as we display the value sent by the app. 



Available target types

Apps can require different types of targets: 

  • String with no specified format, 
  • String with the date-time format,
  • String with the link (URI) format,
  • Number, 
  • Boolean, 
  • Array of strings, 
  • Array of strings with the link (URI) format,
  • Prices.



Multi-locales and multi-currencies

String targets can be simple or multi-locales. 

  • For simple strings, you must choose which locale to use for this target value. 
  • For multi-locale strings, you select a channel if needed, and Akeneo PIM will automatically manage to send values for all locales managed by the catalog and enabled in your Akeneo PIM. 

Price targets can be mono-currency or multi-currencies. 

  • For mono-currency prices, you must choose which currency to use for this target. 
  • For multi-currency prices, as for multi-locale strings, you select a channel if needed, and Akeneo PIM will automatically manage to send values for all currencies managed by the catalog and enabled in your Akeneo PIM. 


When managing products with variations in your Catalog, understanding how to effectively structure your catalog is essential. This documentation guides mapping product attributes and variants to ensure seamless integration.

If your Catalog includes products with variations, your App does not need to push the axis when creating the schema, nor is additional configuration necessary. They will be taken into account by default when mapping is created.

The product model will always include:

  • Its axis attributes with labels.

The product variation will always include:

  • Its axis attributes (code + value)
  • Attributes that are related to variation level + labels

To maintain consistency:

  • Map product model values at the product level.
  • Map product variants at the variant level.

Whether your catalog includes simple products or product models, adopt the same mapping logic. You should map your product models on the product levels and product variants and simple products on the variant level. Consistency across mapping is crucial for simple products, product models, and variants within your catalog.


When your app requests associations from Catalogs for Apps, they are seamlessly transferred to you during import. No additional action from the user side is needed.

These associations sent to the app undergo prefiltering using the same rules as the catalog. As a result, your app will exclusively receive associations that align with the filtering parameters established for the respective catalogs.


Associations type Availability
Associations with quantity Yes 
1-way associations Yes
2-way associations Yes


Associations Scope Availability
Product Yes 
Product Model Yes
Product Group No


PIM sources

Using the type information, the source panel suggests all PIM attributes or properties that match the expected target type or could match the target type after applying transformation functions. 

The source panel suggests as PIM sources the following attribute types:

  • identifier,
  • parent code,
  • family (code or label),
  • categories (code or label),
  • groups,
  • product status (enabled),
  • text,
  • textarea,
  • date,
  • number,
  • measurement,
  • price,
  • simple select (code or label),
  • multi-select (code or label),
  • yes/no,
  • image,
  • single reference entity link:
    • code, 
    • text, 
    • number, 
    • simple select attributes,
    • multi-select attributes,
    • image,
  • multiple reference entity link:
    • code, 
    • text, 
    • simple select attributes,
    • image,
  • asset collection: 
    • code,
    • text,
    • media file,
    • media link,


Please note that we only send the first asset value when you map an asset collection attribute with a string target. 




Select source

To select a source:

  1. Go to the Mapping tab, 
  2. Select a target in the left panel, 
  3. Then, click Add source and select the property or attribute you want to map.



Source parameters

For each source, you can always define a default value when a value is empty for the selected attribute.



Default values 

When the source value is empty

In the source settings, when possible, we display a Default value when is empty field. If you fill in this field, the PIM will send this value when the product's source attribute value is empty. 

When you have no target to map

For string, number, and boolean targets, you can select a Default value when you have no source to map. In this case, the PIM will send the default value you set up as the target value for all your products.


Replace values

When you map one of the following source types, you can choose to replace your PIM values with new ones. 

  • families,
  • categories,
  • simple select attributes,
  • multi-select attributes,
  • single reference entity link: code, label, single option, and multiple options attributes
  • multiple reference entity link: code, label, and single option attributes

To do so, click Replace values in the Sources section. It displays a new screen where you can manage your replacement values. 

For example, in your PIM, you manage different blue colors: denim, dark blue, light blue, etc. But the marketplace you want to connect only manages the blue color. You might want to replace all your blues with the “Blue” value.

Once you are done, click Confirm. It closes the Option replacement screen and brings you back to the mapping.



Sometimes, you might need to transform your PIM data to match specific channel requirements. To do so, you can use the Transformation section. 

In this section, you can find the list of the sources you selected in the section above, a preview using 3 random products' values and the transformation field. 


When the target handles localized values, Akeneo PIM applies transformation per locale. 


In Akeneo PIM you have: 

  • a sku with no value per channel and no value per locale,
  • a color attribute which is a simple select with no value per channel and no value per locale,
  • and a description attribute with value per channel and value per locale. 

For your e-commerce, you configure a transformation to concatenate these 3 attributes to fill in your website product description in several languages. 

Akeneo PIM sends the concatenation of your product sku, the color label in English and the e-commerce channel description in English for the English locale, and does the same for each managed locale. 


Please read the Akeneo function list page to learn more about transformation functions.



Configure value filters

In the Filter the values tab, you can configure data filters to send only the data your app needs.


Available filters

This tab is visible only when the catalog does not contain the mapping. If the mapping is available, the filters are automatically pushed by the app and can't be selected manually.



To filter product values, you can use the following filters:

  • Channels: when an attribute has value per channel, the PIM sends only product values for the selected channels
  • Locales: when an attribute has value per locale, the PIM sends only product values for the selected locales
  • Currencies: the PIM sends only prices for the selected currencies


You connect your e-commerce app with your PIM and want to send only data related to your e-commerce channel.

In the Filter the values tab, we advise you to filter the values on your e-commerce channel as in the following screenshot.


Enable/disable a catalog

Once you finish configuring your catalog, update the Enable status value to Yes in the catalog header.

As soon as you enable a catalog, the app will be able to retrieve your product selection data.

On the contrary, if you want to stop the catalog synchronization between Akeneo PIM and the app, update the Enable status value to No in the catalog header.

All new catalogs are disabled by default when you connect an app. It's up to you to enable them when your configuration is ready.


Please note that catalog can automatically disable if there is a deleted data in the PIM that affects the catalog (e.g., deletion of a channel or locale). 

Also note that if an activated catalog contains a "required" target that is not filled or is no longer filled, the catalog will disabled upon saving. This allows for the work to be saved for later but prevents sending invalid data to the application.