Shopify: merchant plugin guide

About this guide

This guide describes the latest version of ChannelEngine's Shopify merchant plugin, how to install it, how to configure it, and more.

Table of contents

Introduction

Plugin features

Plugin requirements

Install ChannelEngine on Shopify

Install Shopify on ChannelEngine

Orders

FAQs

Introduction

This guide is about Shopify as a merchant plugin, which acts as the source of your product content and handles all orders. If you need information on Shopify as a marketplace, check out the Shopify: channel guide article.

To connect your Shopify webstore with ChannelEngine, you must assign your Shopify account as a private app to ChannelEngine.

Plugin features

Supported	Not supported
Product content	Multiple stock locations1
Orders
Shipments
Cancelations (merchant)2
Marketplace-fulfilled orders
Returns3
Metafields
Three-level product structure
Stock
Return tracking codes4
Product bundles5

1. ChannelEngine imports the stock of all stock locations known to Shopify, and saves the sum of it as the default stock location. Incoming orders only deduct stock from this default location. Check out the FAQs section for further details.
2. Shopify supports only full cancelations. Partial (order line) cancelations are not supported.

3. Marketplace-fulfilled returns are not supported. E.g.: FBA, ZFS, LVB.

4. You can configure return tracking codes on Shopify using the metafield feature. This feature is available only on the latest version of the Shopify plugin. To learn more, check out the article Shopify: return tracking code.

5. Use the ChannelEngine's bundles feature to create product bundles. Bundles created through Shopify are not supported.

Plugin requirements

• Active account on Shopify
• Active merchant account on ChannelEngine

How to request an account

To sign up for an account with Shopify, go to their website. For information regarding pricing, check out the Shopify Pricing page.

Install ChannelEngine on Shopify

To connect your Shopify store with ChannelEngine, you must add ChannelEngine as a custom app in the back-end of your Shopify account. To do so, follow the steps below.

1. On Shopify, go to Apps, Develop apps, and click Create an app.
2. In the Create an app dialog box, enter an App name (e.g.: ChannelEngine). In the App developer field, enter the email address of the owner of this Shopify account.
3. On the Overview tab, click Configure Admin API scopes, and set the following access scopes:
   • Products - read
   • Orders - read and write
   • Inventory - read
   • Locations - read
   • Returns - read and write
4. In the Webhook subscriptions section, in the Event version field, leave the Webhook API version on the latest version. ChannelEngine does not require access to the storefront data.
5. Click Save and go to the API credentials tab. Under Access tokens, click Install app, Install.
6. On the same API credentials tab, the new API credentials are generated and made visible. Reveal the API access token, copy and save it for later.
7. You can now add the API access token to ChannelEngine to establish the connection.

Install Shopify on ChannelEngine

Go to the Setup page of your Shopify plugin on ChannelEngine, and fill out the previously acquired credentials.

Connection

• Admin API access token - the API access token from the Shopify private app page.
• API shop URL - the base URL of your Shopify store. E.g.: yourstorename.myshopify.com. To find it:
  1. On Shopify, look at the address bar. The URL should be similar to 'yourstorename-nl.myshopify.com/admin'. Note that 'yourstore-nl’ varies based on your account setup.
  2. Remove the part after the last slash (/). The remaining part is your base Shopify URL. 
• Shop URL - the base domain of your store, if you use a custom domain. E.g.: ‘yourstore.channelengine.com’ instead of ‘yourstore-nl.myshopify.com’ To find it:
  1. On Shopify, go to Settings, Domains.
  2. Copy the primary domain of your store.

Plugin-specific settings 

• Merchant product number alias on Shopify - the Merchant product number is mapped to the Shopify ID by default, but it can be mapped to the SKU instead. For that, ensure that the SKU is unique for every product. ChannelEngine does not allow multiple products to share the same SKU.
  If the Merchant product number is mapped to the Shopify ID, the SKU is mapped to the Vendor product number on ChannelEngine – and vice versa. Bear in mind that this setting can only be configured once and cannot be changed later.
• Color alias on Shopify - the name of your color attribute on Shopify. By default this is Color, however, it is possible to change it to a different, localized value. To set the color correctly on ChannelEngine's end, the correct attribute name is needed.
• Size alias on Shopify - the name of your size attribute on Shopify. By default this is Size, however, it is possible to change this to a different, localized value. To set the size correctly on ChannelEngine's end, the correct attribute name is needed.
• Material alias on Shopify - the name of your material attribute on Shopify. By default this is Material, however, it is possible to change it to a different, localized value. To set the material correctly on ChannelEngine's end, the correct attribute name is needed.
• Page size - the maximum number of products returned per page. Shopify has a default of 50 items per page, and ChannelEngine uses a default of 250. It is recommended to leave this setting untouched.

Advanced settings

• Shopify Plus enabled - if you use Shopify Plus, enable this setting to enjoy higher API limits. Otherwise, your products are not imported accordingly.
• Product synchronization - disable this to stop the synchronization of your product data between Shopify and ChannelEngine. This can be used if you no longer want the products to be imported into ChannelEngine.
• Generate 3-level product structure - if enabled, the three-level product structure (i.e.: grandparent, parent, and child) is created on ChannelEngine. The parent product on Shopify becomes a grandparent product on ChannelEngine. Parent and child products are generated based on the variant options configured on Shopify, such as color and size. E.g.: if color is the first option and size is the second, by default, parent products are based on color, and child products are based on size. To reverse this structure (e.g.: to base parent products on size and child products on color), adjust the order of options by using the Product option for parent setting. If you have a two-level product structure on Shopify (i.e.: parent and child), keep this setting disabled.
  
• Product option for parent - determine which variant option is used to create the parent product on ChannelEngine. By default, it is set to '1', meaning the first option is used to generate the parent product. However, if color is the first option and size is the second, and you set this setting to '2', the parent products are based on size, and child products are based on color. E.g.:
  
  • Grandparent product SKU: My-Product123
  • Parent products' SKUs: My-Product123-Iphone-X, My-Product123-Iphone-11
  • Child products' SKUs: My-Product123-Iphone-X-Red, My_Product123-Iphone-X-Green
  NB: if you enter a higher number than the number of available variant options, all products that contain less variant options are filtered out of the export to ChannelEngine and are not be available in ChannelEngine.

• Update stock on product import - if enabled, stock quantities on ChannelEngine are synchronized with Shopify during the product import. 
• Default name of shipping lines on order - if enabled, the default shipping lines title, i.e., the name of the shipping-related details attribute on Shopify is set to the shipping service level or service type received from the marketplace. If disabled, you can change it to a different title.
• Shipping lines title - the name of your shipping lines title on Shopify. By default, this is Shipment costs, however, you can change this to a different, localized value, e.g., Shipment Method. To set the shipment costs correctly on ChannelEngine's end, the correct attribute name is needed.
• Shipping lines code (optional) - the code to set on shipping lines for orders exported to Shopify. If left empty, the name is used in lowercase, with spaces replaced by dashes.
• Tracking code is updated asynchronously - if enabled, the tracking code is updated after the shipment has been created.
• Automatic stock updates - if enabled, stock quantities on Shopify are synchronized with and updated on ChannelEngine – and Shopify's internal stock flow is used for orders imported from ChannelEngine. This means that quantities ordered are deducted from the stock available on Shopify, and marked as committed. When the order is fulfilled, the related quantity is also deducted from the committed pool. This ensures that stock quantities remain up to date.
  
  NB: enabling the automatic stock updates conflicts with ChannelEngine's stock reservation setting. To avoid conflicts, go to Settings, Settings, Advanced settings, and toggle the Turn off stock reservation for open orders setting.
• Use the original prices and currency - if enabled, ChannelEngine exports the prices and currency as seen on each order.
• Use tax-excluded order totals - if enabled, ChannelEngine synchronizes order totals excluding taxes.
• Make email addresses unique - by default, Shopify groups customer data by email – and ChannelEngine's generic email is used on orders. If this setting is enabled, unique email addresses are used instead.
• Ignore products with tag - the product tag used to exclude products from synchronization with ChannelEngine. To exclude certain products from import into ChannelEngine, create a unique tag on Shopify (e.g.: 'ignore' or 'no-import') and apply it to the relevant products. ChannelEngine then ignores products containing this tag. The following requirements apply:
  • Use letters, numbers, hyphens, and underscores.
  • Avoid spaces, accents, or special characters. E.g.: é, &, *.
• GTIN alias on Shopify - the Shopify attribute that defines the GTIN of your products. The options are Product barcode and Product SKU. This setting is required for the accurate import of your products into ChannelEngine. 
• Category trail - select the Shopify attribute that defines the category of your products. The default is Product type, but Product category is the recommended option.
• Product tag delimiter on Shopify - select the delimiter used in your Shopify tags. The options are colon ( : ) and underscore ( _ ).
• Include orders fulfilled by marketplace - if enabled, orders fulfilled by marketplaces are synchronized between ChannelEngine and Shopify – with the statuses Fulfilled or Archived. You can select a specific date from which you want to import marketplace orders. Note that this setting cannot be reverted once enabled.
• Enable synchronization of orders fulfilled by merchant - if enabled, orders with the status New on ChannelEngine are synchronized as new orders on Shopify, with statuses Unfulfilled and Paid.
• Export incorrect orders - if enabled, orders containing products unavailable on Shopify are exported. You can select a specific date from which you want to export those orders to Shopify, but no later than three months ago. 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. 
• Export orders with price equal to zero - if enabled, orders with prices equal to 0 (zero) are exported.
• Export orders with closed status - enable this to export automatically closed orders to Shopify. This setting allows the export of orders with a status Closed, based on the Set orders to closed setting on ChannelEngine. To learn more about the setting, check out the article ChannelEngine: stock.
• Send channel liability value to Shopify - if enabled, orders exported to Shopify indicate who is liable for the product taxes – the channel or the merchant – based on the order extra data field VAT_CALCULATION_METHOD_KEY. If disabled, the orders indicate that the liable party for the product taxes is unknown. Note this information is used by tax applications to determine whether taxes are paid and is not visible on Shopify.
• Check for return tracking code - if enabled, ChannelEngine retrieves a return tracking code submitted with a shipment on Shopify. The return tracking code is submitted via a metafield. Once this setting is enabled, three new settings appear on the Setup page, where you can configure the metafield's name, namespace, and key. To learn more, check out the article Shopify: return tracking code.
• Return tracking code metafield name - the name of the metafield used to submit return tracking codes on Shopify. Only specify this if you do not already have a metafield for return tracking codes and want ChannelEngine to create a new one. If an existing metafield matches the namespace and key you provide, ChannelEngine uses that metafield.
• Return tracking code metafield namespace - the namespace for the metafield used to submit return tracking codes on Shopify. The number of characters must be between 3 and 255. You can use letters, numbers, hyphens, and underscores. E.g.: order.
• Return tracking code metafield key - the key for the metafield used to submit return tracking codes on Shopify. The number of characters must be between 3 and 64. You can use letters, numbers, hyphens, and underscores. E.g.: return_tracking_code. The namespace and key together form the full metafield identifier in Shopify. E.g.: order.return_tracking_code
  
  NB: if the specified metafield namespace or key do not match an existing metafield on Shopify, ChannelEngine creates a new one based on the values you enter.
  
• Enable synchronization of merchant returns - if enabled, merchant returns are synchronized between Shopify and ChannelEngine.
• Enable synchronization of marketplace returns - if enabled, marketplace returns are synchronized between ChannelEngine and Shopify.
• A single payment gateway name for channel [marketplace name] - the name of the payment gateway for a specific channel. This is only needed if you track specific payments per channel in underlying systems.
• If all settings have a checkmark, you can switch on Activate synchronization for Shopify. This triggers an attempt to make a test API call to your Shopify environment. If it returns an error, instead of a green toggle, the API access token and/or API shop URL are invalid. Make sure to double-check these settings and try again. If the problem persists, contact ChannelEngine's Support team.
• If the plugin is successfully activated, tasks are automatically scheduled to import products and shipments from Shopify – as well as to export orders to Shopify. You can check the latest executed tasks and their next schedule in the Dashboard section of the plugin's settings.

  

Orders

Orders imported from ChannelEngine appear in the overview under Shopify, Orders.

Note that the buyer's first and last names in the shipping and billing addresses of each order are mandatory. If either of these are empty, the order is synchronized with Shopify without any addresses.

Returns

Make sure that the Comment field on marketplace returns has a value. Otherwise, the return is not synchronized with Shopify.

Phone numbers

Shopify requires phone numbers on orders to be in the E.164 international standard, including the country code prefix. Most marketplaces, however, allow phone numbers in any format.

The E.164 general format must contain only digits, formatted in the following way:

• Country code (1 to 3 digits) - e.g.: 1 (United States), 55 (Brazil), 353 (Ireland).
• Subscriber number (max. 12 digits) - e.g.: 55512345618.

FAQs

Why do I encounter an 'Unsuccessful plugin validation' error? 

You may encounter an 'Unsuccessful plugin validation' error when you try to activate the Shopify plugin. This means that ChannelEngine is unable to connect to Shopify due to an access rights issue.  

1. Make sure the API shop URL is correct. To do this, see Install Shopify on ChannelEngine.
2. Make sure the ChannelEngine IP ranges are whitelisted as described in the article ChannelEngine: IP ranges.

Why is the stock not updated automatically when orders are exported to Shopify?

The Shopify plugin does not subtract or add stock on orders, shipments, or cancelations automatically, but this can be done manually. ChannelEngine offers the option to automatically update the stock when fetching a shipment for products. To find out how to enable this option, check out the Shopify: stock management article.

Why is the stock on ChannelEngine the sum of my stock in each of my locations?

If you have assigned inventory to more than one location on Shopify, it pushes the sum of the stock quantity in each location to ChannelEngine - which in turn displays that value as your current stock. This is done by default, and it is not possible to disable it. E.g.: if inventory location A has a stock quantity of 2, and inventory location B has a stock quantity of 1, the stock shown on ChannelEngine is 3.

Why does ChannelEngine not have a public app?

One of Shopify's requirements to list a public app on their app store is that all users who want to use the app must be able to immediately create an account for that service. 

To avoid a surplus of unused accounts and low-quality integrations, new accounts can only be created by ChannelEngine. This means that all integrations can be made in consultation with ChannelEngine, ensuring that our users are properly guided and benefit from high-quality, tested integrations. 

This means that ChannelEngine is unable to list the ChannelEngine plugin on the public Shopify app store. You can connect your Shopify webstore with ChannelEngine by adding the Shopify plugin to ChannelEngine, and ChannelEngine as a custom app in the back end of your Shopify store. To learn how to do this, check out the Shopify: merchant plugin guide. 

How can I export Shopify product IDs?

Shopify has an export option to generate a CSV file containing all of your Shopify products (Products page, Export), however, it does not include Shopify IDs. Therefore, it is necessary to export your information via one of the alternative methods listed below: 

1. Use a Shopify plugin
   Use the Shopify app store to find a suitable plugin built for the purpose of exporting product data alongside Shopify IDs, such as WebAppsLive ‑ IDs Exporter. 
2. Build your own implementation of the Shopify API
   If you have developer resources or sufficient technical knowledge, you can perform an information fetch from the Shopify API. Use the following API call, where the number of pages and calls is based on the total number of products:
   

   https://shopname.myshopify.com/admin/variants.json?fields=id,product-id,title&limit=250&page=1

3. Use a custom channel on ChannelEngine
   You can create a custom channel on ChannelEngine with all of your Shopify products. These automatically contain the Shopify ID (as the Merchant product number) and the SKU (as the Vendor product number). This option is explained below in more detail. 

Using Google Sheets to enrich Shopify content

1. Create a custom channel on ChannelEngine and add all your Shopify products to it.
2. Once the feed has been generated, download the CSV file. Note that it can take up to one hour after enabling the channel for the feed to be generated.

3. Open the CSV file and copy-paste the columns you want to include in your feed to a Google Sheets file. Alternatively, open Google Sheets, click File, Import, Upload, and select the CSV file.

4. You can add columns containing as much product information and as many attributes as necessary to the spreadsheet. Note that you must keep the column Merchant product number.
   
5. When you have added your product information, publish the file to the web. Choose the option to make the file public, and export it as a CSV file. You can find more information about exporting Google Sheets files as product feeds in the article ChannelEngine: create a product feed using Google Sheets. 
6. Use the public URL generated by Google Sheets file to import your updated product information into your custom channel. For more information on importing product information, check out the article ChannelEngine: product feeds.

How are products' metafields displayed on ChannelEngine?

Products' metafields configured on Shopify are imported into ChannelEngine and presented as custom attributes. Only attributes with values are imported, the others are ignored by ChannelEngine. Changes made to a metafield's value on Shopify are automatically synchronized with ChannelEngine.

Can I view order extra data on Shopify?

Yes. ChannelEngine exports orders to Shopify with order extra data, such as the channel name, commercial order number, and fulfillment type. You can find this on Shopify in the form of note attributes under Additional details.