Akeneo: merchant plugin guide

About this guide

This guide describes how to set up a connection between the Akeneo product information management (PIM) system and ChannelEngine. 

Table of contents

Introduction

Features

Requirements

How to request an account

Install Akeneo on ChannelEngine

• Connect the merchant plugin
• Plugin-specific settings
• Activate the integration

Install ChannelEngine on Akeneo

• Set permissions 

How it works

Best practices

Product feed import

FAQ

Introduction

Akeneo PIM is a solution for gathering, managing, and optimizing product catalogs. Connecting Akeneo with ChannelEngine allows you to synchronize the two platforms.

To connect your Akeneo data with your ChannelEngine account, you can either use ChannelEngine's merchant plugin or export your product information from Akeneo – and upload it as a product feed on ChannelEngine. Both methods are described in this guide.

Features

Supported	Not supported
Product content (including images)	Shipments
Product offers	Returns
Parent, grandparent, and child product relationships	Return tracking codes
Stock	Orders
	Marketplace-fulfilled orders
	Order extra data
	Cancelations
	Multiple stock locations

Requirements

• An active account on Akeneo
• An active account on ChannelEngine
• Akeneo Community or Enterprise version 7.0 or higher

How to request an account

Sign up for an Akeneo account directly on their website. For more information, check out their First steps with Akeneo guide. 

Install Akeneo on ChannelEngine

On Akeneo

Community edition

1. Go to Connect, App store.
2. Click Create an app and enter a name for the integration (e.g.: ChannelEngine).
3. Enter your activation URLs, replacing 'myshop' with the name of your ChannelEngine tenant (as displayed in the URL when you log in to your account):
   • Activate URL - https://myshop.channelengine.net/akeneo/activate
   • Callback URL - https://myshop.channelengine.net/akeneo/callback 
4. Copy your Client ID and Secret. 

Enterprise edition

1. Go to Connect, Connection settings.
2. Click Create. Enter a label (e.g.: ChannelEngine) and select Other as your source. 
3. Copy your Client ID, Secret, Username, and Password.

On ChannelEngine

1. Click Plugins from the left-hand side menu.
2. Locate the Akeneo integration and click Add.
3. On the Akeneo Setup page, scroll down to the Connection section. 
4. Enter the URL for your Akeneo PIM. E.g.: https://channel-engine.demo.cloud.akeneo.com.
   
   
5. Select the preferred Authentication method, depending on your Akeneo edition. The options are:
   • Via the Akeneo app (Enterprise edition) - enter your Client ID, Client secret, and API access token into the relevant fields.
   • Via an API user (Community edition) - enter your Client ID, Client secret, API user, and API password into the relevant fields.

     

6. Click Save.

Plugin-specific settings

Note that attribute codes have a restriction based on the attribute type. E.g.: the Name attribute code must be connected with an attribute with the Text type on Akeneo. Attributes with the types Table, Asset collection, and Reference (e.g.: Reference entity simple link, etc.) are not supported by ChannelEngine due to the nature of their values.

Required

• Category import type - the type of category import. The options are:
  • Default category trail - the default Akeneo category trail. If selected, make sure that the Category key setting is filled out.
  • Custom attribute - the custom category attribute. If selected, make sure that the Category attribute code setting is filled out.
  • Do not update the category - prevents the update of the category trail.
• Category key - the root node key of the category tree. This can be found under Settings, Categories on Akeneo, where you can select the desired category tree and copy the top-level root node.
• Category attribute code - the code of the category attribute on Akeneo. The supported type is Text.
• Name attribute code - the code of the name attribute on Akeneo. The supported type is Text.
• Description attribute code - the code of the description attribute on Akeneo. The supported type is Text.
• Attribute scope - the scope of the attribute. On Akeneo, an attribute can have multiple values – which differ based on the scope. The scope can be generic (e.g.: ecommerce), or specific (e.g.: eBay). Define the scope to set values to be imported into ChannelEngine. E.g.: ecommerce.

Optional

• GTIN attribute code - the code of the GTIN attribute on Akeneo. The supported attribute type is Text.
• Price attribute code - the code of the price attribute on Akeneo. The supported attribute type is Price.
• Stock attribute code - the code of the stock attribute on Akeneo. The supported attribute type is Number.
• Size attribute code - the code of the size attribute on Akeneo. The supported attribute types are Text and Measurement.
• Color attribute code - the code of the color attribute on Akeneo. The supported attribute type is Text.
• Brand attribute code - the code of the brand attribute on Akeneo. The supported attribute type is Text.
• Main image attribute code - the code of the image attribute on Akeneo. The supported attribute type is Text.
• Scoped attributes - the list of attributes that create attributes on ChannelEngine, based on their scope. E.g.: if the attribute Price has values assigned for both the bol and Kaufland scopes, two custom attributes are created on ChannelEngine: Price bol and Price Kaufland. Separate multiple attributes with a comma ( , ).

Advanced settings

• Default locale - the default language for this integration. The options are Dutch, English, French, German, Italian, Russian, Spanish, and Turkish.
• Update stock on product import - enable this to update the product's stock whenever the product import is performed.
• Use Akeneo parent SKU - if enabled, ChannelEngine imports grandparent and parent product SKUs from Akeneo. The SKU becomes the product’s Merchant product number on ChannelEngine. Note that the maximum number of characters for SKUs is 19. If disabled, ChannelEngine automatically creates a unique identifier used as the Merchant product number for parent and grandparent products.
• Import incomplete products - if enabled, ChannelEngine imports product content even if attributes within the scope have incomplete values. If disabled, ChannelEngine refrains from importing products within the specified scope that do not have all attributes mapped.

Activate the integration

To activate the plugin on ChannelEngine, go to the Activation tab and toggle the option Activate synchronization for Akeneo.

Install ChannelEngine on Akeneo

On Akeneo, accept the required authorization request from ChannelEngine.

Set permissions

To set the required permissions, next to the View field, select All under the following sections:

• Category trees
• Locales
• Attribute groups.
  

How it works

Once the merchant plugin is connected, ChannelEngine imports product data every time this data is updated.

ChannelEngine converts products into a usable format to make them available for use on any marketplace. If a required attribute is missing, you receive a notification in your ChannelEngine environment. Manually correcting the missing attribute on Akeneo PIM makes it available for import. 

Best practices

How Akeneo is set up can vary depending on your preferences. However, to ensure seamless synchronization between ChannelEngine and Akeneo, follow the best practices below:

• Use either the 'scopable' or 'localizable' option for attributes on Akeneo. Using both options at the same time is not recommended.

• Depending on your desired setup, create a generic scope (e.g.: ecommerce) or a dedicated scope for each marketplace.

Title and description

Depending on your desired setup, follow one of these best practices for titles and descriptions:

• Generic title and description - it is recommended to create your title and description attributes as 'non-scopable' and 'localizable' attributes. This way, you can create titles and descriptions in the required languages.
• Marketplace-specific title and description - it is recommended to either:
  • Create 'non-scopable' and 'non-localizable' attributes for each marketplace. E.g.: Title Amazon DE, Description bol NL.
  • Create a 'scopable' and 'non-localizable' attribute, such as Marketplace title, and populate it with values for each marketplace scope. To use this setup, you need to have a scope per marketplace, and add this attribute to the Scoped attributes setting on ChannelEngine.

Price and currency

If you use multiple currencies on Akeneo, configuring the Price attribute code setting on ChannelEngine is not recommended as it can cause issues during the product import.

Depending on your desired setup, apply one of these best practices for prices:

• Generic price - create a 'non-scopable' and 'non-localizable' Price attribute on Akeneo, and populate it with values for all currencies.
• Marketplace-specific price - create a 'scopable' and 'non-localizable' attribute, such as Marketplace price, and populate it with values for each marketplace scope.

Unit of measurement

While Akeneo supports the use of multiple units of measurement, it is recommended to use only one unit of measurement per attribute. This ensures the proper import of the attribute into ChannelEngine, with the custom attribute name incorporating the unit of measurement. E.g.: Weight_gram.

Product images

To successfully import images into ChanneEngine, ensure they meet the following requirements:

• Images on Akeneo must have the attribute type set to Text. Other types (such as Asset collection or Image) are not supported by ChannelEngine.

• Images must have a valid URL, and be hosted outside of Akeneo.

Product feed import

Because Akeneo is a PIM system, it has a product export feature that you can use to upload your product offerings to ChannelEngine without having to install the merchant plugin. Both this method and the merchant plugin work well, so it is a matter of preference.

To import your product feed from Akeneo:

1. Follow the steps in the Product export builder article in the Akeneo help center to export your products.
2. Publish the export file to the Web and copy its URL.
3. On ChannelEngine, go to Products, Product feeds, and click Add feed.
4. Paste the copied URL into the relevant field and click Load product feed.
5. Map your data attributes on Akeneo to product attributes on ChannelEngine. A full walkthrough of the steps involved can be found in the article ChannelEngine: product feeds. 

FAQ

Can I choose specific products to export into ChannelEngine?

No, you cannot select individual products to export to ChannelEngine. All products, including their respective attributes, are synchronized between Akeneo and ChannelEngine.

Are all Akeneo attributes imported into ChannelEngine, or only the required ones (i.e.: SKU, Name, Description, etc.)?

All attributes from Akeneo are exported to ChannelEngine. If an Akeneo attribute does not have a corresponding attribute on ChannelEngine, it becomes a custom attribute. E.g.: if the attribute Name has values assigned for both the Amazon and bol scopes, two custom attributes are created on ChannelEngine: Name Amazon and Name bol.

How often is product content imported into ChannelEngine?

Product content is imported into ChannelEngine via the Import product data from merchant task, which runs every 15 minutes.

Can I switch to a different authentication method after activating the plugin?

Yes, it is technically possible to switch to a different authentication method. However, this is not recommended. Each method has its own specific flow described in the Install Akeneo on ChannelEngine section of this guide. Additionally, changing the Authentication method setting does not affect the number of features supported by the plugin.