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.
-
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.
Note
Since the beginning of February 2022, it is no longer possible to create private apps in Shopify, but only custom apps. The difference is in the authentication, which takes place in a custom app via an API token instead of via API key and secret as before. Private Apps that have already been created can still be used, but new connections since then only work via a Custom App.
To be able to connect Shopify and xentral, you first have to find the API token at Shopify or create a new one. To do this, first log in to your Shopify backend as an administrator. To use xentral, you need to create a Custom App by first clicking on Apps and then on "Develop Apps for your store".
On the next page you can open an existing app or create a new custom app. To create a new app, click on "Create an App".
The name for the custom app is freely selectable. Click on "Create App" and you will get to the overview page of the custom app. In the next step you have to set the permissions for the Xentral App.
More information about custom apps can be found here.
Set permissions for xentral app
On the Custom App overview page in Shopify, click "Configure Admin API scopes" to set the permissions. You may be asked to set a status to allow the interface to xentral certain functions. You will then need to set at least the following scopes 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.
After you have set the permissions, click on the "API credentials" tab and you can view the API access token there.
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 Token
Note
For Shopify URL and Shopify Token you have to enter the data from Shopify. You don't have to enter Shopify API key and password there.
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.
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.
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.
This section explains the possible settings in the store 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. This input is only required by users who are connected to Shopify via an existing Private App
-
Shopify Password: Access data from the Shopify backend. This input is only required by users who are connected to Shopify via an existing Private App
-
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.
Information about this tab can be found here.
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.
You can find information about this tab here.
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 Meta fields section.
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.
Information about this tab can be found here.
You can learn more about using Smarty in this helpdesk article: Smarty in the store importer.
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.
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.
Learn how to synchronize stock numbers here.
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.
In some cases, not all orders can be imported from Shopify to xentral. This problem can occur e.g. in case of network problems. To make sure that all orders have been imported, starting with xentral version 22.3 there is the possibility to compare the orders available in Shopify with those in xentral. For the comparison the orders of the last 7 days are used.
To start the comparison, proceed as follows:
-
Open the Shopify API Advanced module
-
Click on Compare Sales Orders in the Action column on the right side
-
Click Compare in the dialog box
After the comparison is complete, you will be told how many orders were checked. If not all orders could be imported, the Shopify order IDs of the missing orders will be listed. These must then be imported manually.
If a large amount of orders (>250) are to be checked, the process may take a while. By clicking on the Refresh button the current progress can be viewed. Since the process runs in the background, the dialog box can also be closed and work with xentral can be continued during this time. If the dialog box is then opened again, the current progress is displayed.
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:
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.
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).
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
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.
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.
If the coupon is not automatically picked on Shopify and imported to xentral, the coupon must be sent manually. If it is automatically picked, it will no longer be imported to 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.
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.
Some meta fields are predefined by xentral. For these fields, master data is transferred from xentral to metafields in Shopify.
|
Field in xentral |
Key / Field name |
Scope |
|
Zolltarifnummer |
harmonized_system_code |
global |
|
Metatitel DE |
metatitle_de |
global |
|
Metabeschreibung DE |
metadescription_de |
global |
|
Meta Keywords DE |
metakeywords_de |
global |
|
Artikelbezeichnung EN |
title |
ml_en |
|
Artikelbeschreibung EN |
description |
ml_en |
|
Metatitel EN |
meta_title |
ml_en |
|
Metabeschreibung EN |
meta_description |
ml_en |
|
Meta Keywords EN |
metakeywords |
ml_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.
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.
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 Shopify.
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.
In general, we recommend performing native article maintenance in Xentral, as image transfer from Xentral to Shopify works fine. However, it is also possible to transfer article images from Shopify to Xentral. It may happen that the transfer does not work for individual article images. If such a case occurs, you can delete the images, re-import them into Xentral and export them to Shopify once from there.