Table of Contents
- Create interface
- All settings at a glance
- Job import settings
- Article import and export settings
- Discount settings
- Settings for the items in the order
- Address import settings
- Communication settings
- Multi-project store (special function)
- Mark as paid in advance
- Confirm order status
- Manual address transmission
- Free text from store interface
- Set total amount and Maximum difference from calculated sum
- Item for postage, COD charge and discount
- Extra sale prices
- Item settings for the online store
- Import of orders from online stores
- Synchronization of bearing numbers
- Export/update items to the store
- Import of articles from the store to xentral
- Payment methods mapping
- Shipping types mapping
- Free field mapping
- Subshop Mapping
- Group mapping
- Store functions: Feature matrix for store interfaces
This article describes the connection of online stores and marketplaces (e.g. Amazon, Shopware, Shopify) to xentral. In each store importer there are general and importer-specific settings, which are explained in more detail here.
Please note that not all store interfaces support all features. An overview of which interfaces offer which features can be found in xentral under Administration → Online Shops → Shop Features.
To create a new store, a new importer can be created under Administration → Online Shops → NEW. Depending on which store system is to be connected, the appropriate module can be selected.
Subsequently, the created interface is reached and the access data can be entered and saved.
General settings can be made.
The following fields must be filled in for this purpose:
- Name → Name freely selectable for the store (will be displayed e.g. in the article and in the import menu).
- Active → Set a check mark so that the interface is active. Interfaces that are no longer needed can be set to inactive.
- Project → Link the store to a project. In the project, the logistics settings can be made
- Pickup mode → Depending on the store interface, there are different options here, e.g.: by status, date or number.
The import mode defines whether the orders should be imported from the store 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.
- Manual (with import center) → The orders are only picked up when the Pick up orders button is clicked.
- Automatically (via process starter) → The orders are picked up automatically by the store on a regular basis. The Shopimporter process starter is required for this.
In addition, further settings are possible:
- Only 1 order per request → Only 1 order per request is transferred from the store.
- Orders in intermediate table → When picking up the orders, the orders are not created directly, but are first saved in an intermediate table for review. Here you can decide which orders should be created and which should be imported later.
- Limit number of orders → Possibility to limit incoming orders at once. If nothing (0) is entered, the default limit of 100 applies.
Settings for store or marketplace
These settings vary depending on the store interface and include, among other things, the fields for the access data that must be entered to establish the connection between xentral and store, which can be, for example, an API URL, an admin username and an API Key (password). However, different data is required per interface.
Below are store specific settings. More information can be found in the articles about the respective interfaces.
On the right there are buttons for various actions that can be performed in the store interface.
Check connection xentral checks whether a connection to the store could be successfully established with the entered access data. If the connection was successful, "success" is displayed. If multiple subshops exist in the store, the subshops and their IDs are listed.
A gray message means that the connection is successful. If the connection fails, a red error message is displayed. In this case, the access data is probably incorrect and must be checked again. Under certain circumstances, orders must be present in the store for the test of the connection to be successful, as this function sends a dummy request for the order pickup to check whether a response comes from the store. If necessary, a test order can be created in the store for this purpose. As of version 19.3, a different request is sent so that the connection check also works without existing orders.
Fetch orders Fetches all orders from the store that match the settings (according to order status, number, etc.). The button must be pressed only in the manual import mode.
Note: Also, make sure that the status messages for "Order open", "Order in progress" and "Order ready" are unique. The same status must not be used in several places.
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 option 'Orders in intermediate table' is activated.
Fetch article list Matches the articles in the store with those in xentral. Missing items are created, already existing ones are updated (currently available for Magento, Shopify and Shopware).
The name, number, item description and default price of the item are matched. So that the article list can be fetched, the process starter article import is required.
All settings at a glance
All the settings that can be made additionally are shown below.
Job import settings
The settings in the options control the type of transfer and synchronization between xentral and store. Please note that not every store interface supports every function. Which store interfaces cover which range of functions can be found in the articles on the individual interfaces
- Use payment method mapping → Payment methods in xentral should be linked to payment methods in the store.
- Use shipping method mapping → Shipping methods in xentral should be linked to shipping methods in the store.
- Mark as paid in advance → Orders from the store are marked as paid in advance in xentral.
- UTF8 encoding → The store importer uses UTF8 encoding (please enable to avoid display errors with special characters etc.!).
- Multi-project store → Items from different projects are offered in this store
- VAT checked + release for shipping → The checkbox 'VAT ID checked' will be set automatically in all orders from the store, so that the VAT check will release the orders for shipping
- Postage → item from xentral that maps shipping costs from the store order as a separate item (more information below).
- Postage reduced → Article from xentral, which should be used to map reduced postage costs for orders from this store.
- Create postage item → If no postage item is stored, a postage item with the name from the store is created and inserted into the order in xentral to map the postage.
- C.O.D. fee as extra item → For C.O.D. orders, the C.O.D. fee is inserted as a separate item in the order
- C.O.D. fee → item in xentral that maps the C.O.D. fee as an order line item
- Report order status → xentral is allowed to report the status of imported orders back to the store
- Disable automatic feedback → this disables automatic feedback to the store, for orders without tracking number. The feedback will only take place after saving the tracking number or by the automatic feedback without tracking number in the transfer module.
- Get any status → All orders will be transferred from the store to xentral, regardless of status
- Free text from store interface → Customer information/customer comments will be transferred to xentral in the field 'Free text' and will therefore be printed on the documents
- Create offers instead of orders → The orders from the store are not created as orders but as offers in xentral
- Deactivate autoship on comment in shopping cart → If the customer has left a comment during checkout in the store, autoship for this order will be deactivated in xentral (thus allowing a manual check of the orders by the employee)
- Report cancellation → If an order is cancelled in xentral, the cancellation will be reported to the store, so that the order gets the status 'cancelled' there as well (currently available for Shopify, Shopware and WooCommerce)Make taxation in third country dependent on shipping address → The taxation for export orders is determined based on the shipping address instead of the billing address
- Set total amount → Total amount of orders will be taken from store for xentral and not recalculated in xentral from item positions
- Maximum difference from the calculated total → range for which the Set total amount setting should apply. Useful e.g. when order totals are rounded to 0.05 currency units or there are rounding errors up to 1 cent
- Overwrite direct debit data in address → The direct debit data of an address in the address master will be overwritten if they were different for a store order of this customer.
Article import and export settings
- Allow stock figures transfer → xentral is allowed to export the stock figures of the items to the store
- Stock basis → Stock level of the item to be reported to the store (saleable or total stock minus reservations).
- Overwrite stock correction value → The stock correction value entered here will be reported to the store for all items and thus no longer needs to be maintained per item in the item master (click to allow stock correction value to be entered)
- Pseudo stock rules → Reports stock numbers to the store according to a set of rules that can be set via formulas. For more info see the helpdesk article "Pseudo stock numbers formulas".
- Allow article transfer → xentral may export articles to the store
- Automatically transfer all changed articles → Checking this box will automatically transfer all changed articles from xentral to the store. This field is related to the "artikeluebertragen" cronjob. When the cronjob is running and there are no articles for export, the cronjob searches for all products associated with a store where this field is active. It then checks each of these items to see if there have been any changes since the last export. If so, the respective item will be added to the list of items to be exported, which will be exported after the check is complete
- Transfer images → xentral may export item images to the store
- Transfer properties → xentral may export item properties to the store
- Transfer categories → xentral may export item categories to the store
- Transfer cross-selling → xentral may export cross-selling links between items to the store
- Transfer scale prices → xentral may export scale prices of items to the store
- Transfer vouchers → vouchers from Shopware 5 are transferred and can be processed in xentral. More info can be found here
- Suppress article text transfer → Export of article texts from xentral to store is disabled for the whole interface
- Pick up article list only create new articles → With the action 'Pick up article list' only missing articles are newly created, but articles already existing in the address master of xentral are not updated
- Take over article number from store when creating → The article number from the store is also created as article number in xentral when the article is imported from the store
- Discount → item from xentral that maps discounts in the store order as a separate item in the order with a negative sales price.
- Discount item tax rate → VAT rate of the discount item used (normal or reduced).
Settings for the items in the order
- Create missing items → Items that are included in the store order but are not found in the address master are automatically created in the xentral address master.
- Fix discounts and postage → Discounts and postage are taken from the store and fixed.
- Description texts from store → Texts from the store are taken over into the article master of xentral
- Article numbers from number range → Article numbers from the number range of xentral are assigned to the articles coming from the store
- Single → Only for articles with the option 'Online Shop Matching' in the article master the above setting is applied
- Item numbers from store → If item numbers from store differ from those in xentral (found via foreign numbers), item numbers from store will be used
- Article description from xentral → The article descriptions from xentral will be taken over into the order items
- Article descriptions from xentral → Article descriptions from xentral are taken over into the order items
- Article descriptions from the store → If the store transfers the article descriptions, these are taken over in the order
- Supplement parts lists → For 'mix & match' items (e.g. bundled items in Magento), the parts lists are supplemented in the same way as in the store
- Special tax rates per items → The tax rates from the store are also taken over for orders with mixed tax rates
Address import settings
- Use existing customers only from project → check box if the customer is to be created with a new address per project (the customer address then exists per project and e.g. per store, i.e. several times in total in xentral if the customer orders via several stores).
- Do not overwrite existing addresses → the new data entered in the store does not overwrite the customer address in xentral (no address update in the master data)
- Manual address transfer
- Adds a button in the address master of all addresses from xentral to manually transfer the address data from xentral to the store.
- Note: Manual address transfer is available only for Shopware 5 interface.
If the store provider is changed, the module in the store importer can also be changed or updated here. This includes, for example, a change from an external importer to a new internal importer.
All general settings as well as all links to articles, categories, foreign numbers, shipping and payment mappings and subshops will then remain, but a new API will be addressed.
Important: All store specific settings will be lost! The access data must be re-entered and saved.
Multi-project store (special function)
This option is only needed if items from different projects are offered in the store.
Example: In a store, some articles are offered that require a different logistics process or for which a special customer check (e.g. requesting an extract from the commercial register) is required directly after the order. These items can be purchased together in this way. However, after picking up the orders after xentral, different processes are triggered (e.g. different e-mail templates, customer check is required, different logistics process, different invoice dispatch, different stationery, etc.).
Mark as paid in advance
This function marks orders with special payment types (special payment types via payment providers, financial institutions) as "prepaid". The traffic light is always set to green for these payment types . So the traffic light with the paid icon does not switch to orange (orders without payment (with prepaid payment types) are normally always orange, because a manual payment release or the linking of the payment with the order via the bank statement is required).
Confirm order status
This option reports e.g. the status shipment "delivered" back to the store. The tracking number and other statuses are also reported depending on the store. In this way, you can see in the store backend which orders are current and which have already been imported or processed.
Manual address transmission
This function allows manual transfer of address data to the store. The manual address transfer shows in Address (Master data → Addresses → a button (prerequisite: the address has the same project as the store), which - when pressed - creates the address in the store. However, nothing is transferred automatically. The manual transfer also shows the password, which is the customer number. The manual address transfer is only available for the interface to Shopware 5.
Free text from store interface
By the following setting it is possible for you to take over the free text (comment field in the store) either in the free text or in the internal remark of the order.Set up the setting for this:
- Load into free text field
- or: load into field internal remark
Practical tip: in logistics, this information can also be displayed as a red box in the shipping processes at the packing table. This information must be confirmed at the packing table. The settings can be found in the system settings (central settings).
Set total amount and Maximum difference from calculated sum
This setting specifies that the total amount transmitted by the store should always be fixed and used when importing orders. xentral then no longer recalculates the total amount from the prices of the individual items, but uses the total amount from the store. This can be helpful e.g. if the store calculates with less decimal places than xentral and thus rounding errors (mostly exactly 1 cent) occur due to the VAT. Likewise, in some countries amounts are rounded to 0.05 currency units, so xentral would detect a difference from the actual total price in this case.
Directly below, in the field Maximum difference to calculated total, you can define the maximum difference between the order in the store and in xentral, so that xentral takes the total from the store and does not recalculate it (and stops the order if a difference was detected).
Item for postage, COD charge and discount
To show shipping costs (postage), cash on delivery (COD) charges and discounts in the items of your orders imported from the store, one item each can be created in the item master of xentral and linked in the interface.
The item stored here is used to display postage/shipping costs as a separate item in the order.
Cash on delivery fee
If the option 'C.O.D. charge as extra item' is enabled in the interface, the C.O.D. charge will be inserted as a separate item in the order, in addition to the normal postage item. So the customer's full shipping cost is made up of these two items: C.O.D. charge + postage.
At the following point a discount article can be entered, to which the discounts of your store will be transferred.
In the input field below you can define how the discount (in the accounting sense a credit note) should be taxed. If the tax rate is to be taken from the article master, then the field does not need to be filled in.
The prerequisite for this is that the item in the item master is set to 'Item is discount' and the % field is left blank:
Extra sale prices
There is also an option in the store settings to specify a price group for which their sales price should be transferred to the store.
As soon as the sales price is created on this group, xentral transfers this sales price to the store and not, for example, the default sales price.
Access data for Xentral Import Plugin
- URL: Enter the URL to the importer here
- ImportKey: 32 characters long security password
- ImportToken: 6 characters long security token
Mode for the setup phase or store conversions
- Demo mode (mode for the setup phase or store changeovers) → The last order from the store is loaded - but the status (of the order in the store) is not changed over, so this order can be imported again and again for demo purposes.
- Single Sync (mode for the setup phase or store conversions) → Only ONE order is ever imported during the import. Use this mode during setup and test phase. This ensures that the orders are imported slowly and one by one and can be checked immediately at the same time. Only when the first 10-20 jobs (generally depends on the daily amount of jobs) have been imported without errors, the hook can be removed and the next batch of jobs can be imported together.
Item settings for the online store
Further settings for importing and exporting items between the store and Xentral can be found directly in the respective item. You can find these setting options here.
Import of orders from online stores
The instructions for importing orders from the online store can be found here.
Synchronization of bearing numbers
Allow bearing numbers transfer
In order to automatically report the stock level of the articles to the store, the "Allow stock figures transfer" must be activated. The stock figure is also reported again, for example, when an order is created with an article. This article is then counted away from the stock that can be purchased.
The automatic reporting of the stock figures to the store takes place when the process starter Stock figures is active and executed.
So that the transfer of the stock figures takes up as few resources as possible, this is not carried out every time for all articles. Only items that have been placed in storage, removed from storage or added to an order since their last synchronization are resynchronized when the process starter runs. For safety reasons, the stock levels of all articles are also synchronized again every 12 hours.
The Stock basis setting defines how the "stock" to be reported back to the store should be composed:
- On the basis of "article saleable", the "calculated stock" in the article is reported back to the online store.
- On the basis of "stock minus reservations", the stock minus the reserved orders is reported back (open non-reserved orders are not taken into account).
Overwrite bearing correction
If this option is activated, the stock correction value can be set globally for all articles in this store. The stock correction value then no longer needs to be maintained per article in the article master. The set stock correction value in the article master of the article will be overwritten by this value.
Prerequisites for the bearing number sync
- In the Shop interface → Settings the option "Allow stock numbers transfer" must be enabled.
- In the item → Online store options the option "Stock numbers sync." must be activated & the item must be linked to the store
Transfer manually: If the stock count of a single item is to be transferred, go to Options under Items → Online Shop and click on the "Export" button.
Automatic transfer: If it is to go automatically, the process starter "stock figures'' must be activated (ideally 5 or 10 minutes). Then the value in the store is cyclically adjusted in case of stock differences between xentral and the store.
Information about the process starter:
Zeitpunkt des Lagerzahlensyncs:
Note on bearing sync:
- The inventory change must happen on xentral side
- xentral remembers what was reported to the store last time
- If this has resulted in a change in stock, exactly these items will be transferred
- A change in the store alone does not trigger a stock change in xentral, but a stock change in xentral triggers a feedback to the store (if no pseudo stock figures are used as stock)
By pressing the following button you can delete the last saved stock values. Subsequently, the cronjob "lagerzahlen" retrieves all new stock levels again and reports them back to the store.
Export/update items to the store
The article transfers exports articles together with the maintained data to the store. Among other things, the online store texts, standard price, weights, sales, etc. are exported.
For the automatic export of articles to an online store, there is the process starter Article transfer. This transfers all articles linked to the store one by one in the background, if the export was triggered in the interfaces via the "Article transfer" area. If an article has been changed, it can also be exported directly to the store at the touch of a button in the article master under Details → Online Shop Options.
If only the stock figures of the articles are to be transferred, since all other article data are maintained in the store, the option "Allow article transfer" should not be set, but only the option "Allow stock figures transfer".
In addition to the possibility of transferring articles from the master data itself, the article transfer can also be carried out via the store interface (Administration → Online stores / marketplaces → *Select interface* → Article transfer). Most of the functions are suitable for online stores (e.g. Shopware 5/6, Shopify), but not for marketplaces (e.g. eBay, Real, Amazon).
Before the functions can be used in the module, the article export must be activated for the respective importer.
Subsequently, the individual actions can be executed as required. It must always be confirmed that the articles are really to be transferred.
The following actions are available for article transfer:
- Reset stock number cache: This is a global function. The action transfers the stock numbers of all articles to all stores & marketplaces. Warning: Depending on the number of items, this function may take several days to complete.
- Reset stock count cache for store items with quantity 0: Reports the stock count only for items with quantity 0. If the store has just started and no item transfer has taken place yet or there has been a problem, this function makes an initial adjustment of the stock counts for all items (analogous to "Reset stock count cache"). This function only works for Shop Importer
- Reset item cache: This is a global function. All article data will be transferred. Warning: This action can take several weeks.
- Load all articles: This action loads all articles in xentral into the respective store. It is possible that articles will be overwritten or updated.
- Load all changed articles: Only changed articles are transferred. Initially, all articles are transferred to the store. At the first execution of this function an index is created, so that from the 2nd execution only changes are transferred
- Cancel transfer completely: This action can be used as a kind of "emergency brake" while an article transfer is already in progress.
- Load article: This function can be used to search for and load individual articles or categories. It can be decided in each case whether matrix or variants are also to be loaded.
Stock numbers sync vs. export article
A completely automated matching is only possible for stock numbers, but not for item export. Therefore, only stock numbers can be reported separately automatically, other fields cannot.
In all other cases, the articles must always be updated individually (in the respective article → Online Shop Options) or collectively via the "Article Transfer" tab in the store interface. In the "Article transfer" tab, either all articles changed since the last export, all articles or articles of a category/matrix can be loaded. These are then added to the list and picked up one by one via the process starter. All relevant fields are always matched, exporting only a specific field is not possible.
Transfer item images
Some store interfaces allow an export of article images from xentral to the store, if they were created in xentral in the article master under files with the keyword standard article image (store image). Only images with this keyword were exported to the store.
During the article export to the store, the images are then exported as well, provided that the interface supports the image export.
Change image order for export in the article master, the sort order can be used to specify the order in which the article images are to be shown in the store. It should be noted that not all store APIs observe the order, although from xentral is always passed. The order is taken over e.g. from Shopware. The first image in the sequence serves there as a preview image.
Import of articles from the store to xentral
Some store interfaces allow an import of articles from the store to xentral via the action "Get article list". Store articles that already existed in xentral will be updated, missing articles will be created. The articles will be fetched by the article import process starter one by one after clicking the action.
An individual item can be imported in the item's master data under Details → Online Shop Options to update it if data has been changed in the store.
In order for the correct article from the store to be assigned, the foreign number must already be linked.
Payment methods mapping
In the "Payment methods" tab, the parameters transferred from the store for the different payment methods can be mapped to the payment methods created in xentral. To do this, the option Use payment method mapping must be activated under Settings. So that unknown payment methods from online stores can be linked to known payment methods in xentral, the parameters transferred from the store are automatically created as an empty entry in the mapping table.
For each payment method, settings can be made as to how orders with this payment method are to be handled.
- Payment method store → Designation of the payment method in the store
- Payment method xentral → Payment method in xentral
- Mark as paid in advance → Mark orders with this payment method as paid in advance
- Auto shipping active → Orders with this payment method are released for auto shipping
- Do not create invoice → No invoice will be created for orders with this invoice
- Fast lane → Orders with this payment method are automatically transferred to the fast lane
- Active → Payment method is active
Shipping types mapping
In the "Shipping types" tab, the parameters for the different shipping types transferred from the store can be mapped to the shipping types created in xentral. For this, the option Use shipping method mapping must be activated under Settings. So that unknown shipping types from online stores can be linked to known shipping types in xentral, the parameters transferred from the store are automatically created as an empty entry in the mapping table.
For each shipping type, settings can be made as to how orders with this shipping type are to be handled.
- Shipping type store → Designation of the shipping type in the store.
- Shipping type xentral → Shipping type in xentral
- Country (comma-separated, two-digit ISO) → restriction for which country shipping type is available (empty = no restriction)
- Fast lane → orders with this shipping type automatically transferred to fast lane
- Auto shipping active → orders with this shipping type are released for auto shipping
- Active → shipping type is active
The textual description of the shipping type for the software interface and the labeling on the documents (printed text on invoice, order, etc.) is done via the mapping in the shipping types (Administration → Settings → Shipping types).
There, the type (= field description in xentral, e.g. "self-collector") is linked to the textual description such as "self-collector" or "yard sale". More details about the setting of the shipping types can be found here.
Shipping method outgoing
If a service has been created as different shipping types, this can be controlled via the "Outgoing shipping type" in the shipping type mapping. Here you can define which xentral shipping type corresponds to which shipping type in the store.
Free field mapping
In the tab "Free fields" can be mapped for some store interfaces (eg Shopware) in xentral with free fields in the store to transfer or update them during export.
Find out free field name from the store
In the Shopware example, the free text management is located under Settings in the main menu:
Here the column name is important for xentral (attr1, attr2, etc.)
Enter free fields
The free fields can then be assigned in the store interface under Free Field Mapping:
If a store has been connected with subshops, the various subshops of the online store can be mapped in the Subshop tab. Subshops are used, for example, for separation by language or domain (e.g. meinshop.de and meinshop.com). A mapping could look like this, for example:
In online stores that transfer customer groups, a group mapping can be set. To determine whether the store importer transfers the customer group information, you can look in the shopping cart of an imported order.
The groups in the store can also be mapped to groups in xentral. The mechanics of this work on the basis of roles. The roles can be used as follows:
- Import → Shop to xentral
- Export → xentral to store
- Customer → Order import adds addresses as customers to the xentral group if they are in the corresponding store group. The option Assign new customers adds all new addresses created via the store as customers to the xentral group.
- Member → During order import, addresses, if they are in the corresponding store group, are added as members at the xentral group. The Assign new customers option adds all addresses newly created via the store as members at the xentral group.
- Articles → Defines which article prices should be transferred to the store and in which price group they end up in the store.
This is how the mapping could look like as an example:
In this case, every customer that is newly created is automatically created as 'Price group 1'. If the customer in the store is a member of the KR33 group, the customer will also be added as a 'Member of the Good Customers group'. The third mapping ensures that in the case of an article export, scale prices of the 'Major retail customers' are transferred as prices for the store group 'Price group for retailers'. This allows you to control which price groups are transferred to the store and where they should end up.
Store functions: Feature matrix for store interfaces
Administration → Online stores / marketplaces → Shop functions
The tab "Shop features" gives an overview of all store interfaces of xentral. There you can see which features a specific store importer supports. Example: In the sixth column of the first row, it can be seen from the icons that xentral's Shopware importer allows both an import (Shopware → xentral) and an export (xentral → Shopware) of item descriptions.
Below, the legend explains the symbols.
- Import and export available → Export of the field from xentral to store as well as import from store to xentral possible.
- Can be switched on/off → It can be set in the store interface whether this field should be transferred.
- Not available → Feature is not available for this importer.
- Not available in store → transfer is not supported by this shop/marketplace
- Export from xentral available → field can be transferred from xentral to store
- Import to xentral available → Field can be imported from store to xentral
- Unknown → Currently unknown if this feature is supported