Table of Contents
With this interface you can connect xentral with Shopify to import orders from there into xentral and manage your items sold in the store in xentral. The connection is done via an API interface (Shopimporter). Creation and sending of delivery bills and invoices is handled via xentral, as well as returns management. Updated order statuses, tracking numbers of shipped deliveries and stock numbers of items are automatically reported back to the store by xentral via process launcher.
Note: We do not currently support the new features of Shopify Online Store 2.0. Among other things, the improved meta fields cannot be addressed at this time. Currently, we cannot guarantee an exact timeframe for implementation, but we will inform you via newsletter as soon as these features are supported.
Features of the interface
- Pick up orders
- Change order status on shipment incl. reporting of tracking number to Shopify
- Synchronization of current stock numbers in case of stock changes
- Feedback of cancellations to Shopify
- Export items from xentral to Shopify and import from Shopify to xentral, including variant and matrix items
- Export item properties and free fields to Shopify
- Reporting of current stock numbers
Note: No product tags can be submitted when exporting items from xentral to Shopify.
Connection
Generate API credentials in Shopify
To be able to connect Shopify and xentral, you first need to find or create the API key in Shopify. To do this, first log in to your Shopify backend as an administrator. Then click on Apps on the right. After that, go to Manage Private Apps.
To create a new key, click on "Create new private app" in the upper right corner. After pressing Save, you will see the new API credentials.
Set permissions for xentral app
You may be asked to set a state to allow the interface to xentral to perform certain functions. At least the following areas must be set with read and write permissions:
- Store content like articles, blogs, comments, pages, and redirects
- Customer details and customer groups
- Inventory
- Orders, transactions and fulfillment
- Products, variants and collections
Important: Please note that you will need to give additional permissions to the xentral app in Shopify if a higher level of functionality is desired. For example, listing items from xentral to Shopify requires read and write permissions in the 'Product information' section. Creating credit notes requires full rights in the 'Draft orders' area.
In case of doubt, it is advisable to grant all rights in question so that the interface can work without restrictions.
Create interface in xentral
Under Administration > Shop Interface > Overview > NEW you create a new store and select the Shopify module.
Note: Up to version 21.1 under Administration > Settings > Online Shops / Marketplaces > NEW.
After you have selected Shopify, you can enter the necessary data for the connection of the two systems in the next step. You received the API key and password in the Shopify backend when you created the app for the interface.
- Shopify URL: Mostly in the form of https://ihre-domain.myshopify.com
- Shopify API Key
- Shopify Password
Note: For Shopify URL, Shopify API key and Shopify password you have to enter the credentials from Shopify. The Shopify token must not be entered. It will be entered automatically when you click on Check connection.
Once you have entered the data, you can test the connection between the two systems using the Check Connection button again. To test the connection, there should be at least one order in Shopify that meets the criteria for a pickup to xentral, as xentral may perform the connection test using a simulated order pickup request.
Typical error messages / problems
To make it easier for you to set up and work with Shopify, below are a few typically occurring problems and the corresponding actions.
Error message: "There are currently no orders in the online stores."
Solution: In Shopify, retrieval is done by date, which means it always retrieves the orders for a specific time period and looks to see if the orders found meet the criteria for import. If an order does not meet the criteria because it has been shipped, unpaid or already imported, you will get this message. You can check if you have activated the option "Only 1 order per request", because then the probability is relatively high that the one retrieved order does not meet the import criteria. Also, you can check if there are any open requests in Shopify. If a token is stored, it sometimes helps to delete it and check the connection again.
Problem: The orders are sometimes not imported.
Solution: To solve the problem, reset the date manually. After that all orders should be imported again.
Quick start
To get started as fast as possible only a few settings and actions are necessary. What is necessary for a quickstart with order import, stock number comparison and feedback of tracking numbers you can read here.
Store settings
This section explains the possible settings in the store interface.
Interface
When you open the Shopify interface settings, you will first land in the Details > Interface tab.
Settings
- Name: Name freely selectable for the store (will be displayed e.g. in the article and in the import menu).
- Active: Check the box to make the interface active. You can set interfaces that are no longer needed to inactive.
- Project: Link the store to a project. In the project you can make the logistic settings
- Pickup mode: In Shopify you can pick up here from a certain date.
- Date from: From this date orders will be picked up, updated when you use the pick up orders function.
- Start interface: No orders will be picked up before this date
- Import mode: Determines whether the orders from the store should be imported manually (by pressing a button) or automatically
- Demo (for testing): The order status in the store is not changed, no articles or stock numbers are transferred
- Manually (with import center): The orders are only fetched when the button Fetch orders is clicked
- Automatically (via process starter): The orders are picked up automatically from the store on a regular basis. The Shopimporter process starter is required for this.
- Only 1 order per request: Only 1 order per request will be transferred from the store.
- Orders in intermediate table: When picking up the orders, the orders are not created directly, but first stored in an intermediate table for review. Here you can decide which orders should be created and which should be imported later.
- Extended logging: If activated, additional entries are stored in the log file. Normally this option is deactivated, because it causes an accumulation of large amounts of data. You can use the option to check the logfile for the actual response from Shopify in case of problems - for example, if the stock levels are not synchronized
- Shopify URL: Your Shopify URL. Mostly in the form of https://ihre-domain.myshopify.com
- Shopify API Key: Access data from the Shopify backend.
- Shopify Password: Access data from the Shopify backend.
- Shopify Token: You are not allowed to enter anything in this field. The Shopify Token will be filled in automatically when you click on Check Connection.
- Transfer prices as net: If checked, the prices from Shopify will be transferred as net prices.
- Also pick up partially shipped orders: Orders will be picked up, but without a coupon
allow sale of variants with stock number 0: Even variants that currently have no stock in the warehouse can be sold - Deduct partially shipped quantities: If the an order is imported to xentral, already shipped items will be deducted. If the checkbox is not set, delivered quantities will be added to the order as if they had not been delivered.
- Also pick up pending payment: Orders that have pending payment will also be picked up
- Send Tracking Emails via Shopify: Sending tracking email is disabled by default through Shopify interface. If the tracking emails are to be sent directly from Shopify, this checkbox can be set. It only needs to be enabled if no tracking emails are sent via xentral (disable in project settings). This is useful if you want to send tracking emails exclusively via Shopify
- Compose variant title from properties: This is a deprecated feature that will be disabled in the future. Please use the matrix product module
- On export, compose option name from property titles: This is a deprecated feature that will be disabled in the future. Please use the module Matrixproduct
- On import, apply options in Shopify to item description: Options from Shopify (such as size, color) will be textually added to the item description
- Stock location: Is mandatory to fill in. The stock location is a mandatory field or a basic requirement for matching the stock figures. If no information is given, the comparison of the stock in xentral with the stock in Shopify will not work.
- Determine shipping tax by items: If checked, if items within an order have different tax rates, the shipping tax will be determined based on the tax group of products with the highest total value. That is, if the most expensive items in the order are discounted, then the shipping costs will be considered discounted as well. If the option is disabled, the value passed by Shopify will be applied
Action:
- Check connection: Checks the connection between both systems
- Pick up orders: Fetches the orders from your store
- Store import intermediate table: Jumps to the intermediate table of the orders from the store. The intermediate table is only filled in manual import mode and if the 'Orders in intermediate table' option is enabled.
In the intermediate table you choose in the left column between "Import", "Garbage" and "Later".
- Import: Job is imported directly
- Trash: Job ends up in the trash and cannot be imported a second time.
- Later: Order can be imported at a later time
- Pick up item list: Imports items from your Shopify store to xentral. Store items that were already in xentral will be updated, missing items will be created. The items will be gradually fetched by the Item Import process starter after the action is executed.
You can learn more about the usage of the individual actions in the section Workflows.
Settings
Information about this tab can be found here.
Payment methods
The payment methods used in the store orders are automatically imported to xentral. If a payment method is not known, it will be created in the interface under Details > Payment methods and can then be linked to a stored payment method in xentral.
For more information on payment method mapping, see the Online Shops article. The type name for Shopify Payments is shopify_payments.
Shipping methods
You can find information about this tab here.
Free fields
Free fields for Shopify are processed and end up in the meta fields in different namespaces:
"global": if the free fields belong to a normal item.
"variant": when the free fields belong to a variant.
The mapping of the free fields determines the name of the metafield where the value is stored. You can find more information about this in the Metafields section.
Subshop
Subshop mapping in the interface is not currently available for Shopify, but must be done through two separate store importers and two private Shopify apps.
Language/Supply Country
Information about this tab can be found here.
Group mapping
Group mapping is not currently available for Shopify.
Smarty
You can learn more about using Smarty in this helpdesk article: Smarty in the store importer.
Workflows
Import articles
It causes errors when you import the following articles from Shopify to xentral.
-Articles in draft mode
-Articles without SKU
To learn how to import items from Shopify to xentral, click here.
Export articles
A special feature of Shopify is that if you export an item that has variants in Shopify that are not created or linked correctly in xentral, those items will be deleted in Shopify.
For more information on how to export items from xentral to Shopify, click here.
Synchronize stock numbers
Learn how to synchronize stock numbers here.
Import orders
Importing orders from online stores is described in this article.
Currently Shopify only imports orders with the status "paid", which do not have the status "shipped". Often orders are paid in the same process, for example with PayPal. To avoid double billing, you should define uniformly per payment method whether the payment processing is already done in Shopify or in xentral. The settings are to be made in the payment method mapping.
The option "Apply options in Shopify to item description on import" allows you to apply property options, e.g. personalization on import, to the item description of the order.
Reporting cancellations
If you have enabled the "Report cancellations" option in the settings, then cancellations of orders from Shopify will be reported to Shopify. Cancellation reporting only sets order status to "Canceled" in Shopify, as credit payout can go through xentral. The payment status remains at "Paid." Refund will not run automatically through Shopify.
The cancellation email from Shopify will not be triggered. Partial cancellations or subsequent discounts are not honored.
This is what the cancelled order will look like:
Special cases / Other information
Shipping costs mapping from Shopify
Postage costs are automatically imported with the order import to xentral.
In xentral, orders with postage costs are supplemented with a postage item and its price. You can define the item to be used as postage item from the item master in the interface in the settings tab. Postage free orders will also be imported with the postage item, but this item will then get a price of 0,00 EUR, so the order is postage free for the customer.
Category transfer from xentral to Shopify
xentral transfers the item category information to Shopify. There, the category is created as a product type (All Products > Edit Product).
This gives you the possibility to build and structure your categories in Shopify in a flexible way. The assignment to the category is then done via the correct assignment of the product type (Categories → Edit category).
Article mapping to xentral
To properly map the articles (products) coming from Shopify to the xentral articles, you need to create the ProductID, VariantID and SKU as foreign number (Master data > Articles > Foreign numbers) in the article master of xentral. The SKU from Shopify is always needed for variants as well as parent items and normal items. Additionally, this mapping is important for article export and import from xentral to Shopify.
For articles without variants, the shopifyproductid must be maintained with the article. This will appear when you call the article and copy the highlighted area from the URL into the browser.
Additionally, you should also maintain the SKU (item number) of the item in the foreign number mapping in xentral.
Shopify URL
View in xentral
For articles with variants you have to distinguish between parent and child articles. For parent items you have to maintain the shopifyproductid (green box).
For child items you have to maintain the shopifyvariantid (blue box) and SKU (item number).
Shopify URL
View in xentral
Locations in Shopify
The "Location" named in Shopify is identical to the warehouse in xentral. The location is important to report the stock correctly.
To do this, you must first correctly define or create the warehouse in Shopify. Then you have to select which warehouse stock the location should run on. By clicking on the "Check Connection" button, the connection will be read into xentral and a comparison of the stock in xentral with the stock in Shopify will take place.
Unfortunately, it is currently not possible to use the same credentials for two stores.
Note: You must fill out the warehouse location, it is a mandatory field or a basic requirement for the comparison of the warehouse numbers. If you do not fill it in, the matching of the stock in xentral with the one in Shopify will not work. 
Gift card items from Shopify
You can create items as gift cards in Shopify to represent amount reductions in orders through gift cards. These can be transferred to xentral during order import.
To do this, the gift card item must be set in Shopify so that it is not automatically picked. Otherwise, the orders will be marked as shipped in Shopify and will not be picked up by xentral.
In xentral, the item must not be a stock item. Non-stock items can be hidden on the delivery bill if desired.
Alternatively, you can also check the Pick up partially shipped orders box. This will pick up the orders, but without the voucher. This leads to the fact that the payment amount does not correspond to the order amount in xentral. Therefore you should use this constellation only in exceptional cases.
Metafields in Shopify
The meta fields in Shopify are similar to the properties of an article from xentral.
However, with some exceptions, meta fields are not visible without additional tools. From a technical perspective, meta fields consist of a key, a value, a type, and a scope.
- Key: The key specifies the name of the meta field, in the example the blue metatitle_en.
- Value: The value is the content of the metafield. In this example "Meta DE".
- Type: The type specifies whether the content of the meta field is a text (string) or a number (integer). By default, xentral creates all meta fields as text.
- Scope: The scope specifies how far the information of the meta field extends. For items with multiple variants, a metafield with scope global means that the value is the same for all variants of the item. A scope of the setting variant means that the metafield has its own value for all variants. In this example the gray global
In xentral in the article master, the meta title can be filled in the texts and descriptions area, for example.
When the article is exported to Shopify, the Meta Title looks like this. In Shopify, this interface can be displayed through additional apps.
Metafields do not need to be created additionally in Shopify. If a value is transferred to a meta field that does not yet exist, the importer takes care of everything.
Example: The meta field "Color" is to be created/transferred for an article and the value to be transferred is "Pink". Then it is sufficient to store the data in the article.
The prerequisite is that the Transfer properties option is activated in the store interface.
For variants, the transfer to metafields works the same way. For the respective variant, you create a property and enter a value. The only difference is that properties created for variants are given the scope variant. This means that each variant in the meta field has its own value.
Predefined meta fields
Some meta fields are predefined by xentral. For these fields, master data is transferred from xentral to metafields in Shopify. Field in xentralKey / Field nameScopeTariff numberharmonized_system_codeglobalMetatitle DEmetatitle_deglobalMeta description DEmetadescription_deglobalMeta keywords DEmetakeywords_deglobalArticle description ENtitleml_enArticle description ENdescriptionml_enMetatitle ENmeta_titleml_enMeta description ENmeta_descriptionml_enMeta keywords ENmetakeywordsml_en. The scope ml_en is created directly by xentral. Shopify gives you the option to create any scope you want. In order to collect the data for the English translation centrally, xentral creates its own scope for this purpose.
Transfer meta fields via free fields
Alternatively, meta fields can also be transferred to Shopify via free fields. In this case you have to set the free field mapping in the importer.
Translating meta fields into other languages
To translate meta fields as well as the contained values into other languages, you can create a property in xentral for this purpose also for another language (e.g. French).
During the article export two new meta fields are created in Shopfiy.
The upper meta field contains the translation of the property value. The scope indicates from which language to which was translated. The key is "Pink", the translation is the value of the metafield. The lower meta field contains the translation of the property name. The scope again indicates from which language to which was translated. It is preceded by a k.
With free fields the translation is realized differently. Here the scope is either global, if a simple article is transferred, or variant, if several variants are transferred. The key changes according to the set language.
