Overview

Importing data is convenient when you want to update your catalog with information from external sources such as vendors or an ERP system.

When importing data, Akeneo PIM extracts data from the file and converts it to save in the PIM.

You can import product data as well as catalog entities such as families, categories, and attributes.

Steps of an import

The import process is straightforward:

1. Create an import profile (see below for more information)
2. Build the file manually or via a third-party application
3. Upload the file in the PIM, or enable the PIM to fetch it from a given path (the file path option is not available in the Serenity offer)
4. Launch the CSV or XLSX file import

What is an import profile?

An import profile defines how an import will be performed. Each profile is based on:

• A code to uniquely identify the profile
• A job that defines what will be imported and in which format (e.g., a product import in XLSX, a category import in CSV)
• A set of configuration fields available as a form in the PIM. Each profile can have its own configuration.

Browse import profiles

To view the available import profiles:

1. Log in with a user account with the permission to View the list of profiles for imports
2. Go to the Imports menu
   
3. To narrow down the list, use the available filters above the grid or the search bar (searches on the label)

To see the details of a given import profile, click on its row in the grid.

Create a new import profile

To create a new import profile:

1. Log in with a user account with Create an import profile permission
2. Go to the Imports menu
3. Click Create import profile
   
4. Fill in all required fields in the pop-up window:
   • A unique code
   • A label to identify the profile more easily
   • A job according to what you wish to import
     
5. Click Save to finalize the profile creation. The profile page is then displayed and you can configure it.

Update an import profile

To update an import profile:

1. Log in with a user account with the relevant permissions
2. Go to the Imports menu
3. Click on the import profile to modify
4. Click the Edit button
5. Make your changes
6. Click Save to update the profile
   

In the Properties tab, you can edit the label of your profile.
In the Global settings tab, available properties depend on the import job. For example, for the CSV product import, you will find the following properties:

Select your import mode

For greater control over product data imports, you can select from three import modes:

• Create or update: updates existing products and creates new ones
• Create only: creates new products and skips any existing ones
• Update only: updates existing products and ignores rows that would create new ones

The import mode selection is available for the following jobs:

• Product import in XLSX
• Product model import in XLSX
• Product import in CSV
• Product model import in CSV
• Product & product model import in XLSX
• Product & product model import in CSV
• Product import with rules in XLSX
• Product import with rules in CSV
• Product model import with rules in XLSX
• Product model import with rules in CSV
• Tailored import in XLSX
• Tailored import in CSV

Import images & files

If you have Image and/or File attribute types in your families, you can import their content directly via the product import profile. To do this:

1. First, export the relevant products or product models via an archive.
2. Then, configure the archive to modify the product/product model file by adding your images and/or files.
3. Finally, import the new archive back into the PIM.

Export the relevant products or product models

1. From the left menu, click Exports
2. From the top right corner, click Create, type a label and a code, and select the job Product export in XLSX or Product model export in XLSX
3. Under Global settings, switch Export files and images to Yes
4. Under Content, select the relevant Image or File attributes
5. Save and click Export
6. Once the job is finished, click Download generated files to get the archive

Configure the archive

1. Open the archive you downloaded
2. Open the Files folder
3. Each subfolder under Files corresponds to a product or product model — folder names match the SKUs or codes of your products or product models
   
4. To add new images or files, open the relevant folders and add your files
5. Open the CSV or XLSX file corresponding to your products or product models
6. Go to the columns corresponding to your image or file attributes
7. Update the filenames to match the names of the files you just added
8. Save your spreadsheet
9. Select the spreadsheet(s) and the Files folder simultaneously and create an archive

Import back the new archive

1. From the left menu, click Imports
2. Select the import profile named XLSX product import
3. Upload your archive and click Import

Duplicate an import profile

To create a new profile based on an existing one:

1. Select the import profile to duplicate
2. Click Edit
3. In the top right corner, click the three dots ... and select Duplicate
4. Enter a label and a code, then click Save

Download and upload an import profile

To copy an import profile from one instance to another (e.g., from staging to production), you can download its configuration and import it into a new profile on the target instance.

Download an import profile configuration:

1. Select the import profile to copy
2. Click Edit
3. In the top right corner, click the three dots ... and select Download Profile Configuration

Upload the configuration to another instance:

1. Create a new profile on the target instance
2. Click Edit
3. In the top right corner, click the three dots ... and select Import Profile Configuration
4. Upload the configuration file you downloaded

Run an import

How to start an import

1. Go to the Imports menu
2. Click on the import profile to execute
3. Click Import now to have the PIM fetch the file from the configured path, or click Upload a file to upload a file manually
4. The execution page displays and refreshes automatically so you can monitor progress

When the import ends, a notification appears in the top right corner of the PIM.

An email notification can also be sent depending on your user configuration. For further details, please refer to the Manage your account article.

With the user groups rights (EE only)

Rights on the product information

For product imports, the PIM applies your permissions based on the user groups you belong to:

• If you own the products in the Clothes category, the import will directly update those products
• If you only have edit rights on products in the Audio video category, the import will automatically create a draft for you instead of directly updating the products
• If you only have view rights on products in the Goodies category, the import will fail for those products with an error indicating you cannot modify them

To learn more, see the Access rights on products article.

Rights on import execution

Execution permissions can be configured per import profile. If you cannot launch an import, check that you have the right to run it in the Permissions tab of the import profile in edit mode. See the Access rights on imports/exports article for more details.

Main identifier and UUID

New import processes with the UUID

The following use cases are supported when running imports:

• No main identifier and no UUID: a new product will be created with a randomly assigned UUID
• Main identifier only, no UUID: a new product will be created with that identifier and a randomly assigned UUID
• UUID only: the product will be updated even if the main identifier is unavailable
• Main identifier only: the product will be updated even if the UUID is unavailable
• UUID to update the identifier: the product will be updated with the new main identifier
• Custom UUID: you can provide your own v4 UUID during product creation

All use cases depending on what you fill in the UUID and main identifier columns:

Combined product and product model import

The combined import allows you to import both products and product models from a single CSV or XLSX file. The PIM reads the entity_type column in each row to determine whether to process it as a product or a product_model.

This is particularly useful when you need to:

• Update a complete product hierarchy (product models and their variant products) in one operation
• Re-import a file previously exported with the combined export profile
• Reduce the number of import jobs required to enrich a catalog with family variants

Create a combined import profile

To create a combined product and product model import profile, select the relevant job:

• Product and product model import in CSV
• Product and product model import in XLSX

Configure a combined import profile

Once the profile is created, click Edit to configure it. The profile contains the following tabs: Properties, Permissions, Global settings, and History.

In the Properties tab, you can edit the label of your profile, configure a storage source, and enable scheduling for automated imports.

In the Global settings tab, configure the following properties to match the format of your import file. The CSV profile includes Delimiter and Enclosure fields; the XLSX profile does not.

Prepare your combined import file

The most reliable way to prepare a valid combined import file is to first export using a combined export profile. This guarantees the correct file structure, column order, and entity_type values.

Your file must respect the following rules:

• The entity_type column must be present and contain either product or product_model for every row
• Product model rows must include a value in the code column, unless an Identifier Generator is active 
• Rows must be ordered so that parent records always appear before their children. If a child product or sub model is listed before its parent, it will not be created. The correct order follows the same depth-first hierarchy as the combined export:
  • Product model A
    • Sub model A1 (child of A)
      • Variant products belonging to A1
    • Sub model A2 (child of A)
      • Variant products belonging to A2
  • Product model B…

Using draft codes for product models with generated codes

When product model codes are generated automatically by the Identifier Generator rather than defined manually, the code does not exist yet at the time you prepare your import file. In this situation, you cannot fill in the parent column of child rows because the parent's code is unknown.

The draft_code column solves this problem. It lets you assign a temporary placeholder code to a product model row. You then reference that same placeholder in the parent column of its children. When the import runs, the PIM resolves the placeholder automatically once the real code has been generated by the Identifier Generator.

How to use draft codes

1. Add a draft_code column to your import file.
2. On the product model row whose code will be generated, leave the code column empty and fill in a unique placeholder value in draft_code (e.g. draft_jacket_001).
3. On any child rows (sub product models or variant products) that belong to that parent, enter the same placeholder value in the parent column.
4. The PIM will replace the placeholder with the real generated code during the import.

Example

The following example shows a file with one root product model whose code will be generated, one sub product model, and two variant products. The draft_code value draft_jacket_001 is used as a temporary reference throughout the hierarchy.

During the import, the PIM generates the real codes for the two product model rows and automatically replaces all references to draft_jacket_001 and draft_jacket_001_M in the parent column with the actual generated codes.