Shopware 6: merchant plugin guide

About this guide

This guide describes ChannelEngine's integration with Shopware 6.

Table of contents

Introduction

Features

Requirements

How to request an account

Installation

Overview

• Product data
• Stock
• Orders
• Shipments

FAQs

Introduction

Shopware 6 is a cloud-based ecommerce solution for B2B and B2C merchants to sell their products and scale their businesses online. This integration with ChannelEngine is a generic, API-based plugin that can be used by all ChannelEngine customers. 

Features

1. While Shopware 6 supports adding multiple sales channels, only one sales channel can be added per ChannelEngine environment. Note that in the context of Shopware 6 integration, a sales channel differs from its conventional understanding on ChannelEngine and essentially refers to a storefront. To learn more, check out the Shopware sales channel article.
2. ChannelEngine only sends returns to Shopware 6 if you have a Rise license or higher with Shopware.
3. Marketplace-fulfilled returns are not supported. E.g.: FBA, ZFS, LVB.
4. To enable sending stock levels to ChannelEngine from multiple stock locations, reach out to your customer success manager or contact the Support team. Your tenant must also have the advanced order management feature enabled.

Requirements

• Active account on Shopware 6
• Shopware version 6.4 or higher*
• Active merchant account on ChannelEngine

*Shopware versions above 6.7.1 may be compatible with the Shopware 6 merchant plugin, but have not been tested, and compatibility is not guaranteed.

How to request an account

To sign up for an account on Shopware 6, visit Shopware's website and request a product demo. 

Installation

On Shopware

Obtain Shopware 6 API credentials

To establish a successful connection between Shopware 6 and ChannelEngine, obtain your API client ID and Client secret by creating a new integration.

1. Log in to your Shopware 6 account and go to Settings, System, Integrations. 

2. Click Create new integration, give the integration a name (e.g.: ChannelEngine), and toggle the Administrator option next to the name field to enable administrator permissions. 
    

   

3. Click Save integration, and then copy the Access key ID and Secret access key. Find more information on creating integrations in the Shopware help center.

Create a sales channel on Shopware

Set up a ChannelEngine sales channel on Shopware 6 as part of the configuration process:

1. Click the plus symbol (+) next to Sales Channel in the menu to create a new sales channel. 
2. In the pop-up window, select whether you want to create a Sales channel with HTML storefront or a headless sales channel (API only). 

3. Configure the payment and shipping methods of the sales channel:
   • Payment methods - add iDeal as a payment method in your sales channel on Shopware. This allows you to create test orders and check the connection between ChannelEngine and Shopware.
   • Shipping methods - by default, only one shipping method, as configured on Shopware, is used with the ChannelEngine sales channel. To assign a different shipping method per order, based on your Shopware shipping rules, enable the setting Set shipping method before order export.

Support multiple countries and currencies

While Shopware 6 allows you to add multiple sales channels within its system, only one sales channel per ChannelEngine environment (tenant) is supported. You can, however, add multiple countries and currencies to a single sales channel on Shopware. For details, consult the Shopware help center article Add a sales channel.

On ChannelEngine

Add the Shopware 6 plugin

1. Log in to your ChannelEngine environment. 
2. From the left-side menu, go to Plugins, Shopware 6, to add the plugin.

Connection

1. Add the URL of your Shopware store in the Shop URL field. 
2. Paste the Access key ID and Secret access key you copied earlier from the Shopware 6 backend into the Client ID and Client secret fields.
3. In the Sales channel field, enter the name of your sales channel from the Shopware 6 backend.
4. In the Sales channel API access key field, enter the API access key of your sales channel. This field is only required if you enable Set shipping method before order export in the Advanced settings. To locate the key on the Shopware 6 backend, go to Sales channels, select your ChannelEngine sales channel, and open the API access section.

Plugin-specific settings

• Order status - (required) indicate with which status you prefer to import new orders from your channels, e.g.: open, in progress, etc.
• Size attribute identifiers - to map your Shopware size attributes on ChannelEngine, enter the identifiers of your size attributes, separated by a comma ( , ). 
  • Find this identifier on the Shopware 6 backend by navigating to Catalogues, Properties, and selecting the size attribute from the overview. The identifier is the last part of the URL, following the slash. E.g.: your-shopware-6-url/admin#/sw/property/detail/'9n6d9j0l3b2m7t9z0ibc8'. 
  • If you leave this field empty, ChannelEngine does not import size attributes from Shopware.

• Color attribute identifiers - to map your Shopware color attributes on ChannelEngine, enter the identifiers of your color attributes, separated by a comma ( , ). 
  • Find this identifier on the Shopware 6 backend by navigating to Catalogues, Properties, and selecting the color attribute from the overview. The identifier is the last part of the URL, following the slash. E.g.: your-shopware-6-url/admin#/sw/property/detail/'9n6d9j0l3b2m7t9z0ibc8'. 
  • If you leave this field empty, ChannelEngine does not import color attributes from Shopware.

• Merchant product number alias in Shopware - (required) select which product ID to sync with ChannelEngine's merchant product number: either your Shopware Manufacturer product number or Product number. This one-time setting cannot be changed after plugin activation. 
  • If you choose Manufacturer product number, your Shopware manufacturer product number is mapped to the Merchant product number, and your Shopware product number is mapped to the Vendor product number on ChannelEngine.
  • If you choose Product number, your Shopware product number is mapped to the Merchant product number, and your Shopware manufacturer product number is mapped to the Vendor product number on ChannelEngine. 

Advanced settings

• Product synchronization - enable the synchronization of products between Shopware and ChannelEngine.
• Generate grandparent products - enable it to create grandparent products and a three-level product structure. 
  • Once this setting is enabled, a field called Custom fields appears on Shopware in the Specifications tab under Catalogs, Products. Enter a value for the grandparent SKU into this field to create the relationship and generate product data for the grandparent. 
  • The data, which is automatically generated for the grandparent product, follows the same logic as is explained in the article ChannelEngine: product feeds. 
  • The longest common name and the minimum price are taken from the associated parent products and used for the grandparent. 
• Inherit parent product images - if enabled, ChannelEngine automatically retrieves the parent's cover image and additional images (if these are available on Shopware) and adds them to the child product. If the parent has no cover image, the child inherits no images from the parent. By default, this setting is disabled, and ChannelEngine only imports those images that are attached to the child product on Shopware. For guidance on how ChannelEngine manages images for child products, check out the section Parent and child images below.   
• Order fulfilled by merchant synchronization - when this setting is enabled, orders that you fulfill are synchronized between Shopware and ChannelEngine.
• Shipment synchronization - enable the synchronization of shipments between Shopware and ChannelEngine.
• Cancelation synchronization - enable the synchronization of merchant cancelations between Shopware and ChannelEngine.
• Import merchant invoices - when enabled, you include your own merchant invoices in the shipment import to ChannelEngine. On Shopware, enable the invoice document feature on your orders. ChannelEngine imports the Shopware-generated invoice with your shipment.
• Enable synchronization of orders fulfilled by marketplace - enable this to include orders fulfilled by marketplaces in the order import.
• Update stock on product import - enable this to update your stock upon the import of products.
• Update prices on product import - enable this to update your prices (e.g.: price, list price, purchase price) upon the import of products.
• Export incorrect orders - enable this setting to export both merchant- and marketplace-fulfilled orders that contain products that are unavailable on Shopware. You can select a specific date from which you want to export those orders to Shopware, but not later than the past three months. Note that you can only configure this setting once, and it cannot be changed afterwards. By default, this setting is disabled, and orders containing unavailable products are not exported. Do not enable this setting together with Set shipping method before order export. 
• Enable check for return tracking code - enable this to capture a return tracking code for marketplaces that require it. Once enabled, a new custom field labeled Return tracking code appears on the relevant orders on your Shopware backend. When creating a shipment for marketplaces such as Zalando, OTTO Market, or About You, enter the return tracking code in this custom field. To learn more, check out the article Shopware 6: return tracking code.
• Enable synchronization of merchant returns - enable the synchronization of merchant returns between Shopware and ChannelEngine. For guidance, check out Shopware 6: returns.
• Synchronization of marketplace returns - enable the synchronization of marketplace returns between Shopware and ChannelEngine. For guidance, check out Shopware 6: returns.
• Use the original prices and currency - when enabled, ChannelEngine exports the original price in the currency that is present on the original order, given that the currency is defined in the channel. If the order uses a currency that is not defined in the channel, then the price is exported in the default currency of the channel. When disabled, the price is exported in the default currency of the channel, with a converted value where necessary.
• Export house number addition as a separate address field - enable this setting to export a house number addition to the Additional address line 1 field on Shopware. When disabled, the street name, house number, and house number addition are exported together to the Street field. 
• Set shipping method before order export - enable this setting to assign a shipping method per order, based on the shipping rules that you configured on Shopware. Before exporting an order, ChannelEngine retrieves the shipping method available for the cart and assigns it to the order. Note that this setting requires a Sales channel API access key, which you add in the Connection step. 
  • If Shopware returns more than one available shipping method, ChannelEngine assigns the first one in the list. To control which method is used, adjust your shipping rules on Shopware.
  • If Shopware returns no available shipping method, the order is exported and Shopware assigns the default shipping method.
  • If the Sales channel API access key is missing or incorrect, orders are not exported and keep the status New on ChannelEngine. A notification lists the affected orders. Correct the key to export them.
  • Do not enable this setting together with Export incorrect orders. Orders containing products that are unavailable on Shopware fail to export.
  • By default, this setting is disabled and all orders are exported with the default shipping method of your sales channel.
• Make email addresses unique? - to create separate users for incoming orders on Shopware, select Yes. ChannelEngine then uses unique email addresses on incoming orders to show that each order comes from a different buyer. If an order has no email address, ChannelEngine assigns a new email address to it, e.g.: no-email123@channelengine.com. Select No to group all incoming orders from ChannelEngine under a single, generic user on Shopware. 
• Root category ID - the ID of the root category (i.e.: top-level category) in the category trail. E.g.: in the category trail 'Clothes > Tops > Long-sleeved tops', the root category is 'Clothes'. 
  • To find the root category on Shopware, go to Catalogues, Categories. Click the root category, and locate the ID in the URL.
  • If a given product's category does not belong to this root category, then ChannelEngine does not import that product's category to its Product details page on ChannelEngine. 

Activation

In the Activation step, activate the plugin and validate the API credentials. A green checkmark indicates that the connection was successful.

Overview

After establishing the connection between Shopware 6 and your ChannelEngine tenant, the following tasks are performed every 15 minutes:

• Exporting product data and product offers, including pricing and stock information, to ChannelEngine.
• Importing new orders to Shopware.
• Exporting shipments to ChannelEngine.

Product data

• EAN/GTIN - to ensure successful import on ChannelEngine, it is important to always include a GTIN for standalone products created on Shopware – even though it may not be mandatory within your merchant system. Standalone products without an assigned GTIN are rejected during import, and an error message is shown on ChannelEngine. Note that this does not apply to parent products, as they are not sellable.
• Categorization - while Shopware 6 allows you to select multiple categories for a product, this is not supported on ChannelEngine. ChannelEngine assigns the product to the first category listed and ignores the rest.

• Variations - Shopware has built-in support for product variations. Child products can be generated from the Variants tab in the product creation menu on Shopware, and are based on properties such as material, color, etc. Stock is assigned to variants separately from the parent product.

  

• Three-level product structures/grandparents - to enable three-level product relationships (i.e.: grandparent products), you must first enable this option on the Setup page of your Shopware 6 plugin on ChannelEngine. The option Generate grandparent products is found in Setup, Advanced settings.

  

Stock

The stock that is exported to ChannelEngine is the available stock from Shopware, which already excludes the stock reserved for open orders on Shopware. To avoid double stock reservations, it is recommended to disable the stock reservation setting on ChannelEngine. Disable stock reservations on ChannelEngine at Settings, Settings, Advanced, Stock.

Multiple stock locations

If your tenant has the advanced order management feature enabled, you have the option to import multiple stock locations and stock levels from Shopware to ChannelEngine. Reach out to your customer success manager or contact the Support team to enable importing multiple stock locations to ChannelEngine.

To import multiple stock locations and their stock levels from Shopware to ChannelEngine, make sure to verify your warehouse settings at Settings, Warehouses on Shopware.

Your Shopware warehouses appear as stock locations on ChannelEngine. 

Use your stock locations on ChannelEngine to create order routing rules. 

Orders

After activating the Shopware 6 merchant plugin, ChannelEngine exports all orders with the status New from ChannelEngine to your merchant system during the initial synchronization. 

Shopware 6 has four default order statuses: Open, In progress, Canceled, and Completed. Newly created orders on ChannelEngine have the status Open on Shopware. 

When an order comes into Shopware from ChannelEngine, ChannelEngine includes the following fields on the order, given that the connected marketplace provides values for these fields. If the marketplace does not provide a value for a given field, then the field is empty:

• Channel ID

• Channel Name

• Fulfillment Type

• Shipping Method

• Pickup Point Number

• Pickup Point Name

• Shipping Service Level

• Intraco VAT Number

• Commercial Order Number

• Channel Order Number

Order extra data

When an order is imported to ChannelEngine from a marketplace, ChannelEngine imports additional data fields that are related to the order, called order extra data. From select channels, including Amazon and Zalando, ChannelEngine imports the order extra data into custom field sets within Shopware that ChannelEngine has created for you.

Shipments

When you mark the delivery status of an order as Shipped on Shopware, ChannelEngine imports those shipments. Shipments created on Shopware are exported to ChannelEngine every 15 minutes. 

Additional information

Parent and child images

• ChannelEngine imports a maximum of 10 images per product from Shopware.
• By default, ChannelEngine imports only those images that are attached to a child product on Shopware.
• To append the parent cover image and additional images to the child product's images, enable the setting Inherit parent product images.
• If the child product already has 10 images on ChannelEngine, then no images are imported from the parent on Shopware.
• If the parent has no cover image on Shopware, then no images are added to the child.
• If new images are added to the child on Shopware, these images are added first to the child, then the parent images, up to a maximum of 10 images.

FAQs

Can I have multiple languages/Shopware 6 stores connected with ChannelEngine?
There are two options for multi-language and multi-store support. While Shopware 6 does support multiple sales channels, only one sales channel can be used for the connection per ChannelEngine environment. Therefore, you can have two separate ChannelEngine accounts – and connect each one to a different Shopware 6 store. Alternatively, you can use a single ChannelEngine account and include your translated product data fields as custom fields.

Can I retrieve marketplace order extra data via Shopware 6?
Yes, on select channels, it is possible to retrieve order or order line extra data via ChannelEngine’s Shopware 6 plugin. Check out the Order extra data section of this article.