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.

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 shipment 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.
   • Shipment methods - only one default shipment method, as configured on Shopware, can be used with the ChannelEngine sales channel.

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.

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 identifier - to map your Shopware size attribute on ChannelEngine, enter the identifier of your size attribute. You can 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'. Note that if you leave this field empty, ChannelEngine does not import the size attribute from Shopware.

• Color attribute identifier - to map your Shopware color attributes on ChannelEngine, enter the identifier of your color attribute. You can 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'. Note that if you leave this field empty, ChannelEngine does not import the color attribute 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. Note that this setting is disabled automatically if you enable order routing in the tenant. If you want to use multiple stock locations and order routing with a merchant plugin, you need to opt out of stock updates via the plugin.
• 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. 
• 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. If the return tracking code is not provided, ChannelEngine rejects the shipment. 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. 
• 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.

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.