Shopify: merchant plugin guide

About this guide

This guide describes ChannelEngine's Shopify merchant plugin, including how to install it and how to configure it.

Table of contents

Introduction

Plugin features

Requirements

How to request an account

Installation

Overview

• Content
• Orders
• Shipments
• Returns

FAQs

Introduction

The Shopify merchant plugin acts as the source of your product content to your connected channels and handles all orders coming from your connected channels. 

To connect your Shopify webstore with ChannelEngine, there is another plugin available: Shopify as a channel. For information on Shopify as a channel, check out the Shopify: channel guide article. 

Plugin features

1. Shopify supports only full cancelations. Partial (order line) cancelations are not supported.
2. Marketplace-fulfilled returns are not supported. E.g.: FBA, ZFS, LVB.
3. Configure return tracking codes on Shopify using the metafield feature, which is only available on the latest version of the Shopify plugin. To learn more, check out the article Shopify: return tracking code.
4. Use ChannelEngine's bundles feature to create product bundles. Bundles created through Shopify are imported into ChannelEngine by default but have limited functionality. (See the note below.) 
5. To enable multiple stock locations, see Installation, On ChannelEngine. Only stock locations and inventory are imported from Shopify to ChannelEngine. ChannelEngine cannot specify the stock location when exporting orders to Shopify. To enforce stock locations on new orders, the Shopify store owner must manually configure the Shipping and delivery settings on Shopify.

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 pricing information, check out the Shopify Pricing page.

Installation

On Shopify

To connect Shopify with ChannelEngine, you must add ChannelEngine as a custom app via the Shopify Dev Dashboard:

1. Log in to the Shopify Dev Dashboard. Use the account that is associated with your Shopify store.
2. Click Create App.
3. Enter an App name (e.g.: 'ChannelEngine')

4. Set 'https://shopify.dev/apps/default-app-home' as App URL.
5. Untick Embed app in Shopify admin.
6. Leave the Webhook API version on the latest version
7. In the Access section, click Select scopes, and set the following access scopes:
   1. Products - read
   2. Orders - read and write
   3. Inventory - read
   4. Locations - read
   5. Returns - read and write
   6. Metaobjects - read
8. Make sure to leave the Optional scopes and Redirect URLs empty, and leave Use legacy install flow unticked.
9. Click Release, and leave the Release this new version? pop-up empty. Click Release again.
10. Go to your new app’s Home tab, and click Select distribution method. 
11. Select Custom distribution. If you do not see the Distribution section on the right side of the screen (under the Installs section), click Install app to install the app to your Shopify store. Skip to Step 16 in this case.
12. In the Store domain field, enter the base URL of your Shopify store. E.g.: 'http://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.
13. Untick the Allow multi-store install for one Plus organization checkbox. (The Shopify merchant plugin only connects to one store, as a measure to avoid data errors.)
14. Click Generate link.
15. Copy your app’s Install link, and open the link in another browser tab to install your app to your Shopify store.

16. Copy the Client ID and Secret and save them for setting up the merchant plugin on ChannelEngine.

On ChannelEngine

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

Connection

• Shopify app type - select Dev dashboard app to authorize the API connection with OAuth2.0. 

• Client ID - the client ID from the Shopify Dev Dashboard.
• Client secret - the client secret from the Shopify Dev Dashboard.
• 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. This one-time setting cannot be changed after plugin activation.
  • If you choose Product SKU, your SKU is mapped to the Merchant product number, and the Shopify ID is mapped to the Vendor product number on ChannelEngine. Ensure that the SKU is unique for every product. ChannelEngine does not allow multiple products to share the same SKU.
  • If you choose Product ID, your Shopify ID is mapped to the Merchant product number, and the SKU is mapped to the Vendor product number on ChannelEngine.

• 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.: one variant option), keep this setting disabled. Otherwise, your products are not properly imported into ChannelEngine.

• Product option for parent - (appears only if Generate 3-level product structure is enabled) 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

• Enable multi stock location support - if enabled, stock levels are sent to your products' corresponding stock locations on ChannelEngine, instead of to one default stock location. Make sure to set up advanced order management on ChannelEngine first.
• Update stock on product import - if enabled, stock quantities on ChannelEngine are synchronized with Shopify during the product import.
• Update prices on product import - if enabled, prices 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.

• Enable automatic stock updates - if enabled, stock quantities on Shopify are synchronized to ChannelEngine – and Shopify's internal stock flow is used for Shopify orders imported from ChannelEngine. This means that ordered quantities are committed from the stock that is available on Shopify, and marked as committed. When the order is fulfilled, the related quantities are also deducted from the committed pool.

  NB: if you turn on Enable automatic stock updates, Shopify stock data conflicts with ChannelEngine's stock reservation feature. To avoid conflicts, go to Settings, Settings, Stock, and toggle the Turn off stock reservation for open orders setting.
  NB: if Enable automatic stock updates is turned on, and you see the following error appear on ChannelEngine: error_message: {Line items Unable to reserve inventory} code: INVALID fields: order, lineItems, then turn off this setting, if you know that all your Shopify orders are channel-fulfilled.
• Use the original prices and currency - if enabled, ChannelEngine exports the prices and currency as seen on each order.
• Submit order prices excluding VAT - if enabled, ChannelEngine synchronizes order totals excluding sales tax/VAT.
• 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. This is useful for orders originating from marketplaces like Shein, which use a default email address (e.g.: no-reply@shein.com). Without unique emails, multiple orders could be incorrectly linked to the same customer.
• 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.: é, &, *.
  • Enter only one tag in this field, multiple tags are not supported.
• GTIN alias on Shopify - (required) 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 alias on Shopify - (required) select the Shopify attribute that defines the category of your products. The default is Product type, but Product category is the recommended option.
• Enable synchronization of orders fulfilled by marketplace - if enabled, orders fulfilled by the marketplace are synchronized to your Shopify system with the status Shipping not required. Once enabled, the option you select cannot be changed. Please ensure that you want this option enabled. 
• Enable synchronization of orders fulfilled by merchant - if enabled, orders to be fulfilled by the merchant are synchronized to your Shopify system. Orders with the status New on ChannelEngine are synchronized to Shopify with statuses Unfulfilled and Paid. 
• Export orders with price equal to zero - if enabled, orders with prices equal to 0 (zero) are exported.
• Export orders with closed status - if enabled, you automatically export Closed orders from ChannelEngine to Shopify with status Shipping not required. Consider enabling this setting if you enable the Set orders to closed after import setting in Settings from the side-bar menu 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.
• Enable 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 T&T metafield key - (appears if Enable check for return tracking code is enabled) 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
  • Return T&T metafield name - (appears if Enable check for return tracking code is enabled) 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 T&T metafield namespace - (appears if Enable check for return tracking code is enabled) 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'.

    NB: if neither the specified metafield namespace nor key 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.
• Shipment synchronization - if enabled, shipments 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.

Activation

• In the Activation step, if all settings have a check mark, 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.

  

Overview

Content

ChannelEngine imports your product content from Shopify, giving you a streamlined overview of your product catalog on ChannelEngine. 

Once your product data is imported into ChannelEngine, you can continue adding content to your catalog directly on ChannelEngine via a product feed.

Use product feeds to enrich Shopify content

1. Create a custom channel on ChannelEngine and add all your Shopify products to it. For detailed instructions on setting up a custom channel, check out ChannelEngine: custom channels.
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 data 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 data, host the file on the web as a CSV file. Choose the option to make the file public. 
6. Use the public URL generated by the Google Sheets file to import your updated product information into your custom channel. For more information on importing product data via a product feed and hosting options for the feed file, check out the article ChannelEngine: product feeds.

Metafields

Shopify metafields are imported into ChannelEngine as custom fields. The following applies to metafields:

• Import logic - only metafields with values are imported; empty metafields are ignored.
• Synchronization - changes made to a metafield value on Shopify are automatically synchronized with ChannelEngine.
• Supported types - in addition to text, you can submit single images (type: Image). Each image is imported to ChannelEngine as a URL in a custom field. 
• Unsupported types - metafields of types List of images, Video, and File are not supported.

For more details on ChannelEngine custom fields, check out ChannelEngine: custom fields.

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 is empty, the order is synchronized with Shopify without any addresses.

Address validation

It is possible to enable or disable ChannelEngine's address validation feature on your tenant. Your address validation settings affect the format of the buyer's address on orders that you receive from ChannelEngine.

• If address validation is enabled on your tenant, ChannelEngine sends the address components (e.g.: house number, street name, etc.).
• If address validation is disabled on your tenant, then ChannelEngine sends the original address lines that come from the channel (e.g.: Line 1, Line 2, etc.).

 For guidance on configuring address validation on your tenant, check out ChannelEngine: address parsing.

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.

Set up order tags on Shopify

Set up order tags on Shopify to label incoming orders from ChannelEngine, e.g.: bol-nl, amazon-de, etc. For guidance on setting up order tags to label incoming orders, check out Shopify: set up order tags.

Order extra data

ChannelEngine exports orders to Shopify with extra data fields – including the channel name, commercial order number, address type (home, pickup point), and fulfillment type.

The extra data that comes in with the order differs per channel. Consult specific channel guides to view which extra data fields are sent with orders from those channels. Check out ChannelEngine's channel guides. 

On ChannelEngine, view the order's extra data at Orders, Order details, Extra information.

On Shopify, you can find the order's extra data in the order's Additional details.

Shipments

Partial shipments (order lines that are shipped separately) are correctly imported to ChannelEngine with their quantities and the overall shipment ID of the shipment line. Shipped order lines are set to the Combined status on ChannelEngine. 

Returns

Make sure that the Comment field on channel returns has a value. Otherwise, the return is not synchronized with Shopify. The comment field is fillable via ChannelEngine directly in the order details at Orders, Order details, Comment.

FAQs

Why do I encounter an "Oauth error shop_not_permitted" error?
You may encounter an "Oauth error shop_not_permitted" error when activating the Shopify plugin. This error indicates that ChannelEngine cannot connect to your Shopify store because the API credentials entered in the Setup step are incorrect.

To resolve the error, make sure you log in to the account that is associated with your Shopify store during Installation and when creating a custom app in the Shopify Dev Dashboard. The client credentials grant only works when the app that you create and the store belong to the same Shopify organization.

To verify that your Shopify app and the store belong to the same Shopify organization, check out the Troubleshooting steps in Shopify's article Exchange credentials for a token.

Why is there no address on the Shopify order?
If the City field is missing in the order address details, Shopify removes the entire address from the order. This does not block the order export from ChannelEngine. However, due to Shopify’s default behavior, the order on Shopify does not include any address details.

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, check out the section Install Shopify on ChannelEngine above.
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 automatically subtract or add stock on orders, shipments, or cancelations, 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 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 on the backend of your Shopify store.

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). Once you set up a custom channel on ChannelEngine, you have the added benefit of using a dynamic product feed to enrich your product content directly on ChannelEngine. For guidance, check out the section Use ChannelEngine to enrich Shopify content above.