Exporting Products

Example use case

Let's say we want to export the following Products from a Project to a CSV file:

• Red wines
• White wines

Create template file

The "Product exporter" command requires a template that defines which Product Attributes should be exported.

How to define a Product Type

Let's assume we set up a ProductType named "Drinks" that includes attributes that are characteristic for wines: country, color, and flavor.

• The country attribute of AttributeLocalizedEnumType includes values for "France" and "Germany" in the English and German languages, because the Project supports both languages.
• The color attribute we have modeled as localized enum type too with the fixed values red and white, again for values in the English and German languages.
• The flavor attribute is modeled as an AttributeSetType of localizable enums to allow selection of multiple localized enum values in the English and German languages.

The flavor attribute has the following settings:

• It is an AttributeSetType of localizable enums to allow selection of multiple localized enum values in the English and German languages.
• It has a constraint value of CombinationUnique.
• It is searchable and not required.

We set all those attributes as searchable to include them in the search index, otherwise we would be unable search for Products based on these attributes.

Add Product values to the template

We are now ready to create the template for the export tool. The template is a CSV file that contains one line with comma-separated values of the values to include in the Product export.

For the example use case we are interested in the standard Product information, like productType, variantid, and sku. These columns can be added as follows:

productType, variantId, sku

Furthermore we'd like to export the Product name and description. As these attributes are localized strings that have values in the English and German languages, columns will be needed for each language: name.en, name.de, description.en, and description.de. The template should now read:

productType, variantId, sku, name.en, name.de, description.en, description.de

The attributes color, country and flavor that characterize the wines should also be included. For the country attribute we again provide a column for each language. These columns will be filled with the label of the AttributeLocalizedEnumValue that are defined for each language. For the color as well as the flavor attributes we put just one column without the language identifier. This way these columns will be filled with the key of the localized enum values, which is sufficient for this example.

With these additions the template now has the following structure:

productType, variantId, sku, name.en, name.de, description.en, description.de, color, country.en, country.de, flavor

We also want to export the prices of each ProductVariant together with the taxCategory that is assigned to each Product. For this we add another two columns to the export template, one named prices and the other named tax.

The tax column is an exception in the naming convention of table headers. Usually, the column name is identical to the field name of the API object.

From ProductData we'd like to export the categories, the categoryOrderHints and the slug. We are only interested in the English slug in this example, so we add the slug.en column to the template. Product images cannot be exported to a CSV file, but by adding the images column a list of URLs to the location where the Product images are stored will be included.

Our template finally has the following structure:

productType, variantId, sku, name.en, name.de, description.en, description.de, color, country.en, country.de, flavor, prices, tax, categories, categoryOrderHints, slug.en, images

The template should be saved as a CSV file.

Export all products

Now let's use this template with the ImpEx Product export command by dropping on the respective area of the ImpEx tool:

Click Run command.

Once the export process terminates successfully, click Download file. A file named "exported-products.csv" will be downloaded to your computer.

"exported-products.csv" contains all the published Products in your Project. Meaning, if you had other Products than the wines from the example they will also be included in this file.

This table provides an example of how "exported-products.csv" should appear.

Exported example Products

As we can see in the table, many values are easy to read, others need some more explanation on how to interpret them:

Some values are only listed in the master variant row (where the variantID is 1). For example, values that are common to all Product Variants (such as productType, name, description, tax, categories, categoryOrderHints and slug) are not repeated for other Product Variants.

The Product description in the example may contain HTML markup (<p>) around the text that has been added by the Merchant Center's text editor.

The color column contains the key of the localized enum, in contrast to the origin columns, which contains the localized labels of the enum values instead.

If multiple values have been given for the flavor attribute of a Product Variant its values are separated by semicolons, as it is shown for dry;smoky and dry;fruity in the table. This also applies to the categories and the images columns, listing all the categories the Product belongs to and the images from each Product Variant.

The prices in the exported file can be interpreted as follows:

Let's have a look at the Merchant Center how the prices of the Merlot Product are modeled:

• EUR 1499 shows the price in Euro cents for the master variant (equal to 14.99 EUR).
• EUR 999;EUR 0#gift-items represents the two prices for variant 2 separated by a semicolon:
  • 9.99 EUR for all countries and all Customer Groups
  • 0.00 EUR for the channel #gift-items

On the Riesling Product there are prices defined for a particular country and for particular Customer Groups:

In the exported data for the Riesling Product we can see how the price information country and the Customer Group is represented:

• DE-EUR 999 Default represents the price of 9.99 EUR for Customers in Germany of the Default Customer Group
• DE-EUR 599 LoyalCardHolders represents the price of 5.99 EUR for Customers in Germany who are members of the LoyalCardHolders Customer Group.

These two prices appear in the same table cell of the prices column, separated by a semicolon.

In a real Project the number of products can easily grow into thousands. In such cases you might want to only export certain Products, and you would be happy to have a way to specify which products should be exported. The ImpEx tool allows you to specify a filter that is set in the where parameter of the tool.

Export certain Products only

Let's say we have several Product Types and only want to export Products from a specific Product Type.

First we need to get the id of this Product Type. You can find the Product Type id in the Merchant Center. Go to the Drinks Product Type and view the page URL. The id will be part of the URL as indicated in the below screenshot:

Based on this example we'd use the id b2d637cd-19bc-4677-8c37-64ac31431686. This will be different in your Project.

This id can now be used in a query as below:

productType(id="b2d637cd-19bc-4677-8c37-64ac31431686")

In the ImpEx tool, use this query in the Specify where predicate field.

After executing the Product export with the same template used in section Export all Products, the resulting "exported-products.csv" only includes Products from the specified Product Type.