ChannelEngine: create and update product bundles in bulk via CSV

About this article

This article explains how to create and update product bundles in bulk using a CSV file.

Table of contents

Introduction

Choose an upload type

Create and review your CSV file

Required headers

Upload your CSV file

Examples

View bundle upload history

View the validation report

Common errors

FAQs

Introduction

CSV uploads are useful when you need to add a lot of product information or manage many bundles at once. You can use a CSV file to create new bundles, edit existing ones, and edit bundle compositions – which products make up a given bundle and their respective quantities – in bulk. Upload product bundles in bulk at Products, Product bundles.

To manage bundles in other ways, check out ChannelEngine: product bundles (web interface) and Merchant API: product bundles (API).

Choose an upload type

First, choose whether you want to do a broad create/edit or if you want to only edit a bundle's existing composition. Click Upload CSV, and decide which of the below options to choose:

• Create or edit bundles: create new bundles or edit their name, price, GTIN, and other details.  
  • To edit only the general bundle details, leave the composition values in your CSV file empty. See Edit general bundle details without changing the composition. 
  • To create or change bundle composition along with the general bundle details, enable the Also update bundle compositions toggle, and fill in the composition values.
• Edit bundle composition: leave general bundle details untouched, but change which products are included in a given bundle and their quantities. Only include the following headers in the file: mpn_bundle and productN_mpn, productN_qty, productN_pricepercent in your file.

Create and review your CSV file 

Your CSV file must meet the following requirements:

• The CSV file must use the comma ( , ) delimiter. Other delimiters such as semicolons ( ; ), pipes ( | ), or tabs are not supported.
• Prices must use two decimal places, be greater than zero, and not contain thousands separators. Use a dot ( . ) as the decimal separator, e.g.: 59.99. 
• Specify the price percentage of each bundle part instead of the raw price per bundle part. This way, the price of each bundle part is greater than zero and adds up to the total bundle price.
• Duplicate Merchant product numbers on bundle parts (i.e.: product1_mpn) are not allowed in the file. Instead, use the product_qty values to increase the number of units per product within your bundle.
• Duplicate Merchant product numbers on bundles (i.e.: mpn_bundle) are not allowed in the file. If you use a Merchant product number that was created earlier, it updates the existing bundle with the latest details and does not create a new one.
• Merchant product numbers tied to parent products are not allowed.
• Your CSV file must contain the expected set of headers, even if you do not fill out values under those headers. The locations of the file's headers and their values are fixed, i.e.: header #1 needs to contain a unique mpn_bundle for your bundle, header #2 must contain a unique ean_bundle, etc. See Required headers for details on all the headers that you need to include in your file.  

Required headers

Required headers for upload type: create or edit bundles 

The table below shows which headers and values are required if you select Create or edit bundles. Make sure that every header appears in your CSV file, even when you leave its value empty.

*This value is required if you choose the Create or edit bundles upload option and enable the Also update bundle compositions toggle.

Required headers for upload type: edit bundle composition

The table below shows which headers are required if you select Edit bundle composition. Make sure that every header appears in your CSV file, even when you leave its value empty.

Header descriptions

• mpn_bundle - the bundle's unique Merchant product number. The maximum number of characters is 64. If your CSV contains an mpn_bundle that belongs to a previously deleted bundle, ChannelEngine revives that bundle instead of creating a new one.
• ean_bundle - the bundle's unique GTIN, such as an EAN or UPC. This GTIN must not belong to another product on ChannelEngine. When you edit an existing bundle, enter the bundle's own GTIN.
• name_bundle - the bundle's title. The maximum number of characters is 256. This value is required when you edit an existing bundle. If it is empty, the import fails.
• img_link - the bundle's main image. The header must be included, but the value can be left empty. The maximum number of characters is 512. Do not enter non-URL values, e.g.: 'N/A'. If you provide the bundle's image link via a product feed, you do not need to provide a value here.
• description_bundle - the description of your bundle product, the bundle's Description field on ChannelEngine. If you provide the bundle's description via a product feed, you do not need to provide a value here. 
• price_bundle - the total price of the bundle product, the value of the bundle's Price field on ChannelEngine. The value must be a valid price. To use the current Price of the product, use the string value 'default'. 
• product1_mpn - the Merchant product number of the bundle's first product. This product must be known to ChannelEngine.
• product1_qty - the quantity of the first product included in the bundle.
• product1_pricepercent - the percent of the total bundle product price that represents the first product included in the bundle, also known as the percentage split.
• product2_mpn - the Merchant product number of the bundle's second product. This product must be known to ChannelEngine.
• product2_qty - the quantity of the second product included in the bundle.
• product2_pricepercent - the percent of the total bundle product price that represents the second product included in the bundle, also known as the percentage split.
• productN_mpn, productN_qty, productN_pricepercent - the additional composition values of each additional bundle part. 

Upload your CSV file

1. From the sidebar menu, go to Products, Product bundles.
2. Click Upload CSV. 
3. Choose an upload type: Create or edit bundles or Edit bundle composition.
   • If you choose Create or edit bundles, enable Also update bundle compositions to change bundle composition along with the general bundle details. Your CSV file must contain the composition values.

Edit general bundle details without changing the composition

To change the name, GTIN, or price on an existing bundle without changing its bundle parts:

1. From the sidebar menu, go to Products, Product bundles.
2. Click Upload CSV, and choose Create or edit bundles.
   • Disable Also update bundle compositions. (If already disabled, keep disabled.)
3. Make sure that your file includes every required header listed in Required headers for upload type: Create or edit bundles.
4. Select your CSV file. 
5. Fill in values for mpn_bundle, ean_bundle, name_bundle, and price_bundle on the given bundles. 
6. Leave the composition values empty.

See the example Only edit general bundle details.

Examples

For templates, check out the files at the bottom of this article. 

Create or edit bundles

For Create or edit bundles uploads, include all the required headers. The example below creates or updates the general details and composition on two bundles that each contain two products.

mpn_bundle,ean_bundle,name_bundle,img_link,description_bundle,price_bundle,product1_mpn,product1_qty,product1_pricepercent,product2_mpn,product2_qty,product2_pricepercent
COFFEE-SET-01,8711000442296,Coffee Lover's Starter Set,https://example.com/img/coffee-set-01.jpg,Everything you need to start brewing at home.,89.99,CM-DRIP-1000,1,70,MUG-CER-350,2,30
KNIFE-DUO-02,8711000442232,Chef's Knife Duo,https://example.com/img/knife-duo-02.jpg,A chef's knife and paring knife in one set.,54.50,KNIFE-CHEF-20,1,70,KNIFE-PAR-9,1,30

Only edit general bundle details

For Create or edit bundles uploads that only change the bundle details, keep every required header, and leave the composition values empty. The example below changes the price on an existing bundle to 79.99. Leave Also update bundle compositions disabled.

mpn_bundle,ean_bundle,name_bundle,img_link,description_bundle,price_bundle,product1_mpn,product1_qty,product1_pricepercent,product2_mpn,product2_qty,product2_pricepercent
COFFEE-SET-01,8711000442296,Coffee Lover's Starter Set,,,79.99,,,,,,

Only edit bundle composition

For Edit bundle composition uploads, include only the composition headers. The example below updates the composition of two bundles that each contain two products.

mpn_bundle,product1_mpn,product1_qty,product1_pricepercent,product2_mpn,product2_qty,product2_pricepercent
COFFEE-SET-01,CM-DRIP-1000,1,70,MUG-CER-350,2,30
KNIFE-DUO-02,KNIFE-CHEF-20,1,65,KNIFE-PAR-9,1,35

View bundle upload history

Once you select the CSV file for upload, ChannelEngine starts processing it. To see the status of the processing task on ChannelEngine, click View bundle feed upload history.

The table shows the following columns:

• Date - date of the file upload.
• Name - name of the uploaded CSV file.
• Type - the type of the file.
• Status - the status of the file upload:
  • Success - if ChannelEngine processed the whole file.
  • Partial success - if some bundles were processed successfully.

  • Failed - if every bundle had validation errors.

    NB: if file processing fails, ChannelEngine sends a notification to your tenant. To receive it, make sure the Product bundles import failed notification is enabled in your tenant. See ChannelEngine: how to configure notifications.
• Report - the button that takes you to the report if the upload resulted in errors. 

Use the search field to find a specific file, and the pagination at the bottom of the page to browse older uploads.

View the validation report

Click Report to open the Validation report for a specific file upload. Each row corresponds to one error.

• Error - the description of what went wrong, e.g.: Sum of the price percentages should be 100. Bundle quantity must be a positive integer. For details on other errors, see Common errors.
• Field name on ChannelEngine - the field in the file where the error occurred.
• Value - the value of that field in the file.
• Merchant product no. - the Merchant product number that the failed bundle refers to.

To receive the full report by email, click Download CSV. Correct the errors in your file and upload it again.

Common errors

FAQs

Can I update only the price of an existing bundle?
Yes. Use Create or edit bundles with the Also update bundle compositions toggle disabled. In your file, fill in mpn_bundle, ean_bundle, name_bundle, and the new price_bundle, and leave the composition values empty.

What happens if I leave a bundle part out of the CSV?
If you explicitly choose to update the composition when uploading your CSV, the part is removed from the bundle. Always include every part that you want to keep in the bundle when updating your bundle compositions.

Does editing a composition affect existing orders?
No. Each order keeps the bundle composition that applied when the order was placed. That composition is also used for eventual shipments, cancelations, and returns.