Shopify: channel guide

About this guide

This is a ChannelEngine guide on Shopify as a channel. Here you can find information on how to connect your Shopify webstore with ChannelEngine.

Table of contents

How to request an account

Associated costs

Channel features

Channel-specific requirements and exceptions

Settings and configuration

Setup

Mappings

Listed products

Additional information

FAQs

How to request an account

To start selling via Shopify, you need to create an account on its website. ChannelEngine supports connections with the Shopify Advanced and Plus plans. Basic and Grow plans are not supported. These plans do not provide access to buyer data, including addresses, which makes it impossible to import orders from Shopify.

Associated costs

The costs related to using Shopify are found on the pricing section of its website.

Channel features

Settings and configuration

Setting up each channel on ChannelEngine follows the same flow, though not every channel includes the steps listed below.

1. Go through the Setup.
2. Create a Product selection.
3. Complete the Categorization.
4. Set up the Mappings: content, offers, and carriers.
5. Configure the Pricing: rules and currency conversion.
6. Fill in the Stock settings.
7. Finish the Activation.
8. Check the Listed products overview.

Channel-specific requirements and exceptions

Setup

On Shopify

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

1. Open Shopify Dev Docs.

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:

   • Assigned fulfillment orders - read and write
   • Customers - read and write
   • Content - read and write
   • Discounts - read and write
   • Draft orders - read and write
   • Fulfillments - read and write
   • Inventory - read and write
   • Locations - read and write
   • Merchant-managed fulfillment orders - read and write
   • Order edits - read and write
   • Orders - read and write
   • Products - read and write
   • Product listings - read and write
   • Publications - read
   • Returns - read and write
   • Shipping- read and write
   • Third-party fulfillment orders - read and write (if you make use of third-party-logistics)
   • Translations - read and write (only if Additional languages is configured)

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.

*If you have previously connected your Shopify store with ChannelEngine via Shopify's back-end platform, then you do not need to modify your current installation setup. Continue to ensure that ChannelEngine has access to the above access scopes.

On ChannelEngine

Once your Shopify account is active, add the channel to your ChannelEngine environment and go to its Setup step. The following settings can then be configured:

Connection

• Shopify app type 
  • If you wish to authorize the API connection with a permanent API token, select Legacy admin app. This option is suitable for most existing users of the Shopify merchant plugin on ChannelEngine.
  • If you wish to authorize the API connection with OAuth2.0, select Dev dashboard app. This option is suitable for new users of the Shopify merchant plugin or existing users that wish to use OAuth2.0.

• If you selected Legacy admin app as Shopify app type:
  • Admin API access token - the API access token from the Shopify private app page.
• If you selected Dev dashboard app as Shopify app type:
  • 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

• Location identity on Shopify - on Shopify, go to Settings, Locations. Open the default location. You can find a number after /locations/ in the URL. This is your location identity. Add this number so ChannelEngine can update your stock and orders.

• Currency - enter the currency you want to use for prices and shipping costs, using the ISO standard currency code. E.g.: AUD, EUR, USD, etc.

  NB: make sure to align the Currency setting with the Shopify settings. If these settings do not match, ChannelEngine cannot export prices – causing the product offers export to fail.
• Additional languages - select from the list of languages in which you want to export product content. Before you can use this setting, you need to make sure that the Translations scope has the required permissions. The following attributes are translated: Title, Body HTML, Option 1-3).
• Extra metafields to product export - lets you specify extra product data. The name of the metafield can contain up to 30 characters. For more information on metafields, check out the Metafields section below.

Advanced settings

• Set orders to closed after import - when enabled, ChannelEngine sets order statuses to Closed, and orders are not handled. Instead, orders are handled on Shopify.
• List products on all sales channels - if enabled, ChannelEngine publishes all your products to all sales channels.
• Notify customer of shipment/cancelation - if enabled, ChannelEngine prompts Shopify to send shipping confirmation and order canceled notifications.
• Include shipping costs for cancelation refunds - if enabled, the grand total of the order lines is refunded, including the shipping costs.
• Notify customer on return/refund - if enabled, ChannelEngine prompts Shopify to send an order refund notification.
• Restock items in case of refunds - if enabled, ChannelEngine automatically restocks products in the Shopify warehouse.
• Delay orders with gifted order lines - if enabled, ChannelEngine delays importing orders to allow gift card transactions. This setting is added because gift card orders take longer to process on Shopify.
• Cancelations are handled by Shopify - if enabled, you manage merchant cancelations directly on Shopify – ChannelEngine does not export any cancelations initiated by you to Shopify. To send merchant cancelations from ChannelEngine to Shopify and import cancelations initiated on Shopify, contact the ChannelEngine Support team to enable the dual cancelation workflow.
• Payment ID - if enabled, payment IDs are added to the order extra data for this channel.
• Enable fallback for empty billing addresses - if enabled, ChannelEngine automatically fills out empty billing address fields based on details from the customer's data. If Shopify does not have the customer's data, ChannelEngine uses their shipping address. This is useful for orders placed on a channel other than your webstore, such as a brick-and-mortar store, and ChannelEngine requires billing information to save order data in its database.
• Order prices tax option - specify if the prices in incoming orders already include tax or not. If the prices do not already include tax, then ChannelEngine calculates the unit tax from the order data and adds the unit tax to the unit prices. For guidance on how to leverage ChannelEngine to track VAT/sales tax on your orders, check out ChannelEngine: VAT settings.
• Set region as code in order address - select Yes to map the Shopify property province_code to Region. Select No to map the Shopify property province to Region.
• Enable order force cancelation – by default, orders with New or Requires correction status on ChannelEngine are eligible for cancelation. Enabling this setting also allows cancelations on unshipped orders. The order status is updated to Canceled on ChannelEngine and is synced across both platforms. A cancelation notification is also sent to the customer. 
• Order statuses to import as paid orders - select the order status(es) to treat as Paid and imported as new orders into ChannelEngine. The default status is Paid, but you can also choose Authorized and/or Pending. Note that even if an order is still marked as Pending on Shopify (i.e.: payment is not yet completed), it is imported as Paid on ChannelEngine, even if you choose that option.
• Use Shopify order name as Commercial order number - configure the commercial order number to use the Shopify field Order Name.
• Order name prefix to strip from Commercial order number - remove characters from the beginning of an incoming order's Commercial order number.
• Use advanced image mapping - when enabled, image attributes become available under Content mappings, allowing you to define custom positions for your images. If this setting is disabled, images follow the default order – parent product images are mapped first, followed by child product images.
• Order fulfillment status filter - if you want to filter incoming orders by their fulfillment status, select one or more fulfillment statuses to import, e.g.: unfulfilled, on_hold.   

Mappings

All products (required)

• SKU - the product's Merchant product number. To link to existing products, this attribute should be the same as the SKU field on Shopify.
• Title - the product's name.

All products (optional)

• Barcode - the product's EAN.
• Body HTML - the product's description. 
• Cost price - the unit cost of the item for the merchant.
• Country of origin - the country where the item originated.
• Export images - indicate if you want to export images whenever you update your product content (Yes). Disable exporting images whenever you update your product content (No) if, for example, you want to preserve the current configuration of images on your listings while updating other attributes. 
• Fulfillment service - the ID of the fulfillment service associated with the variant.
• Grams - the product variant's weight in grams
• Handle - this value is automatically created from the product title.
• Inventory policy - indicate whether customers are allowed to place an order for the product variant when it is out of stock, i.e.: backorder.
• Media position 1-10 - if Use advanced image mapping is enabled, this attribute defines the order in which an image or video appears on the marketplace, e.g.: enter '1' for first position, '2' for second position, etc. All media must be mapped in sequential order. Additionally:
  • Product families - a parent and all its children share the same position set. If a parent has media, then place these in the first positions, and place its children's media in the following positions. E.g.: parent product media receives positions 1-5, and child media receives positions 6, 7, and so on.
  • Multiple pieces of media cannot be mapped to the same position.
  • The same image URL cannot be mapped to multiple positions.
• Media type 1-10 - indicate Image or Video. 
• Media URL 1-10 - URLs of images or videos. For each URL, specify the Media type. 
  • If not using Use advanced image mapping, the position is based on the order in which the URLs are mapped and the listed product IDs of the children, with the parent first.
  • When working with variations, map all media to the parent; then, assign one image per child.
  • For children, the media in Media URL 1 is always an image; do not map a video to Media URL 1 for children.

Example - child with Use advanced image mapping enabled

• Media URL 1 - https://mymedia.url.com
• Media type 1 - image
• Media position 1 - 10
• Media will appear in tenth position on the channel.

Example - parent with Use advanced image mapping disabled

• Media URL 10 - https://mymedia.url.com
• Media type 10 - video
• Media will appear in first position on the channel.

• Option 1 - the value of the variation theme, e.g: '26 cm'. Maximum 255 characters. For guidance on setting up product variations for a Shopify channel, check out the section below Product variations on Shopify or ChannelEngine.
• Option 1 key - the variation's theme, e.g.: 'diameter'. Variants of the same product must all share the same option key.
• Option 1 position - indicate on what level this variation appears on the Shopify channel

Example - Options for a 26cm yellow steel pan 

• Option 1 key - diameter
• Option 1 position - 2 
• Result - yellow, 26cm steel pan
• Option 1 position - 1 
• Result - 26cm, yellow steel pan

• Option 2-3, Key, Position - use these options to generate more variations, like color or size. Maximum 255 characters.
• Product type - the product category, using free text. 
• Published  - indicate Yes or No.
• Requires shipping - indicates whether the product variant requires shipping.
• Tags - enter a comma-separated list of tags that have been added to the product. Tags should be mapped only for parent products and not for variations. Each product can contain up to 250 tags, and each tag can contain a maximum of 255 characters.
• Vendor - the product's brand.
• Weight - the variant's weight.
• Weight unit - the weight unit used to measure the variant. Valid values are: 'g', 'kg', 'oz', and 'lb'.

Offer

All products (required)

• Export strategy - decide if you want to export content; choose configurable combinations for content, offers, price, and stock. 
  • If you choose a "stock only" export strategy, then it is not mandatory to map price attributes.
  • If you send only offers, offers are matched to products via the SKU (Merchant product number).
• Price  - your selling price. If you use pricing v2, this attribute does not appear in Mappings.

All products (optional)

• Compare at price - sets the from-to pricing and works as the product's catalog price. If you use pricing v2, this attribute does not appear in Mappings.
• Taxable - indicate if the product is taxable.

In Mappings, Offer mappings, the following offer attribute may appear on this channel, if this channel uses pricing v2:

• Allow promotion below min price - set it to ‘true’ to allow the promotion price to drop below your product's minimum price. 

In Mappings, Fee group mappings, map the marketplace fee group ID of the product.

Listed products

Shopify does not state whether a product is published or not. The only visible activity of the integration is the running tasks and their statuses on ChannelEngine. At first, the status of a product is set to Created. After it is created on Shopify, it changes to Updated.

Note that when the creation of the product does not go well, Shopify only provides you with minor feedback. This feedback is shown under Reason, below the Last import from channel selection.

Additional information

Add products

To create new products on your Shopify backend, ChannelEngine needs to perform three tasks: export the product content to Shopify, export the offers, and export product images. When all three tasks are completed, the products are shown correctly in your Shopify account. Check with your Customer Success Manager or Onboarding Specialist when these tasks are scheduled for the Shopify channel, so you know how long it takes to see your new products online.

Link to existing products

To link to existing products on your Shopify backend, set up the correct SKU of each Shopify product in the mapping attribute SKU. Make sure to inform your Customer Success Manager or Onboarding Specialist before you do that – and do not activate the channel until you get the go-ahead. ChannelEngine must update the export product setting on the backend for you.

Product variations on Shopify or ChannelEngine

The only way to create product variations on Shopify is to first set up a correct grandparent-parent-child structure on ChannelEngine. Once this is set up, you must fill out attributes Option 1-3 in Mappings. E.g.: if you have a t-shirt in various colors and sizes, Option 1 must be connected to the attribute Color and Option 2 to the attribute Size. If you have a grandparent-parent-child structure set up on ChannelEngine, it is no longer possible to set up the products on Shopify as standalones.

Grandparent products

To disable or enable exporting grandparent products to ChannelEngine, get in touch with your contact person at ChannelEngine.

When disabled, ChannelEngine creates a product family for every parent under a grandparent product. When enabled, ChannelEngine treats grandparents as the Shopify parent, and the following applies:

• All grandchildren are treated as Shopify children and are nested under the grandparent product.
• Parent products are ignored.
• Parent-child families are not affected.
• Standalone products are not affected.

In either case, you need to map the content attributes Option 1 and Option 2 to correctly set up the variations. Note that if you have already exported products to Shopify via ChannelEngine, you need to take the following steps before enabling or disabling this setting:

1. Remove all products from the Shopify backend.
2. Request the deletion of your listed products.
3. Save your existing product selection one more time.
4. Run the content and offer exports.

Metafields

Metafields is a Shopify functionality that allows you to send additional information about your products, collections, orders, etc., that is usually not captured via the Shopify back-end platform. This is a particularly useful feature if you are using a PIM system or a product feed and want to send extra product data to your Shopify store. For a detailed explanation of metafields, along with examples of how they are used, check out the Shopify help center article Metafields.

On ChannelEngine, select custom fields to send as metafields to your Shopify store at Setup, Plugin-specific settings. In the Extra Metafields to product export field, select the custom field(s) that you want to send as metafields and click Save. ChannelEngine exports your custom fields as metafields to your Shopify store.

For an explanation on how to create and manage custom fields, check out ChannelEngine: custom fields. 

The following requirements apply to the metafields:

• Maximum character length - 30 (the field name); none (the field value).
• Plain text and new line characters (i.e.: \n) are supported.
• HTML formatting is not supported.

ChannelEngine exports your chosen metafields on either the parent product (i.e.: the Shopify product) or the child product (i.e.: the Shopify variant), or both, depending on where you map the given custom field in your ChannelEngine product feed: 

• Custom field mapped on a parent product on ChannelEngine - metafield is created on the Shopify product.
• Custom field mapped on a child product on ChannelEngine - metafield is created on the Shopify variant.
• Custom field mapped on a standalone product on ChannelEngine - metafield is created on the Shopify product and Shopify variant; a standalone product translates to a Shopify product with a single variant.

Returns and refunds

While you can create a merchant return directly on the Shopify backend, buyer-initiated returns (i.e.: marketplace returns) are not imported and are therefore not visible on ChannelEngine. 

You can also initiate a merchant return on ChannelEngine as a refund. When creating a return on ChannelEngine, it becomes a refund on Shopify, triggering the workflow to mark the refund as paid out.

Payment information

To view the information related to each payment you receive via Shopify, follow the steps below:

1. On your Shopify channel, go to the Setup step and click Advanced settings.
2. Enable the Payment ID setting.

You can then view the payment details in your incoming orders, including the payment method and payment ID. The payment ID allows you to match the orders on ChannelEngine to the information received from your payment provider.

Shopify supports the following payment methods: credit_card, cash, android_pay, google_pay, samsung_pay, shopify_pay, amazon, klarna, paypal, unknown, other.

Order extra data items

When an order is imported to ChannelEngine, ChannelEngine also retrieves extra data items related to the order itself – or to order lines. This extra data is specific to this marketplace. An explanation of each can be found below: 

Order extra data

Order line extra data

* Conditional fields are only displayed if the channel provides a value. 

FAQs 

My shipments are no longer exported to Shopify, and the 'Channel status' displays 'Error: the API client does not have the required permission(s).' What is wrong?
That error is related to the permissions Shopify needs to provide ChannelEngine with. To solve it, refer to the Setup section of this guide – and make sure to grant all required permissions. Once this is done, get in touch with ChannelEngine to 'reset' all shipments that have been stuck.

Why is my order not imported?
ChannelEngine fetches Shopify orders from Shopify with the use of an order filter to prevent filtering through huge lists of orders every time ChannelEngine checks for new orders.

This filter's parameters are:

• The order is created in the last 7 days (from now).
• The order has the financial status Paid.
• The order has the status Open.

If the order does not comply with all three parameters, it will not turn up in the results and will never be imported on ChannelEngine. E.g.: if you have an order in Shopify that was set to paid after 3 days after creation, it will not appear in ChannelEngine.

How often does each task run on Shopify?