You are currently viewing documentation for Linnworks Desktop, if you are looking for documentation, click here.

Website Integration - Gateway


Integration with generic carts such as osCommerce, ZenCart, nopCommerce, Interspire, OpenCart, x-cart and so on is done by deploying a gateway script to your website and setting up integration scripts. The role of gateway is to query the underlying e-commerce cart database and return results in XML format. Linnworks communicates with the gateway script by sending database queries (scripts) to the gateway and parsing the results.

This documentation outlines the process of deploying the gateway script to your website and configuring scripts.

Please Note : Generic website integrations support TLS certificates up to version 1.1. This is due the version of the .net Framework used during the development for the Linnworks desktop application

Integrating website cart

In order to deploy the gateway script you will need to following

  • FTP login details (FTP server name, username and password)
  • Please note that SFTP is not supported
  • Know the location of files where your website cart is installed
  • Underlying database details – server name, username, database name and password

To add new website cart integration, go to Settings > Channel Integration > Add New Channel and select Generic Integration from the list. You will be prompted with the Integration Wizard.

Step 1 – Select Website Cart

Select the website cart type. We have developed scripts for most common website carts already. If you have bespoke website cart or the e-commerce platform you are using is not on the list – you will need to create Bespoke Website integration (read Generic Website – Bespoke websites)

Ensure you have selected the correct integration script. For example there are several variations of zenCart – the one that supports product variations and the one that doesn’t. If you are using product variation mod on your zencart e-commerce platform you must use Zencart Generic with variations.

Step 2 – Deploy Gateway script

In order to allow Linnworks to communicate with the website cart, you need to deploy a gateway script. This requires you to specify FTP details for the script to be uploaded to your website and database connection details .

  • FTP Server path – Full path to where the file should be uploaded. Notice, this should be FULL path, and not just FTP server name. For example if the IP of the my server is and it has folders htdocs, which in turns contains the website cart files, in this instance zencart – the full server path will be ftp://
  • FTP Username – ftp server username
  • FTP Password – ftp server password
  • Site URL – the URL where the uploaded gateway can be reached. This will normally be your site URL. If you have uploaded the gateway to a different folder, you need to reflect this in the Site URL.
  • Database Server  - MySQL or MS SQL server name for connecting to your website cart database. 
  • Database name – the name of the website cart database on the database server.
  • Database username – login name for connecting to the database
  • Database password – login password for connecting to the database


If you don’t know your database connection details, you need to find config file on your website and extract this information. The location and the name of the config file is different for each website cart. Generally PHP + MySQL based website carts have include folder which contains file.
Click Deploy Script to upload the gateway script to the website and test the connection with the database.

See Generic Integration Gateway Deployment - Error Messages for most common error messages

Step 3 – Settings

Here you need to specify the name of the channel you are integrating. This name will appear in the subsource of the order. This name cannot be changed once the website is integrated.

In addition some scripts require default values to be specified, such as default language or default currencies. If the script requires additional parameters the Default Values table will be displayed. 


Step 4 – Table Validation

The integration wizard confirms that your database contains all necessary database tables. If you have table prefix for each table in the database, the wizard will work it out and prompt it automatically. The wizard will not let you go forward if all the expected table can be found in the database.


Step 5 - Order Status

Here you need to specify what order statuses you want to download. Generally website carts have multiple order states. For example, zencart has Pending for placed and unpaid orders, Processing for Paid orders and Delivered for shipped orders. For zencart, 2-Processing status should be selected for Order Status to download and 3-Delivered for Order Processed/Shipped status.

Do not select processes/shipped/delivered orders in the Order Status to download – this will cause Linnworks to re-download all your orders every time you synchronize, which will put an enormous strain on your website and your system.

Once the website is integrated the only way to change the order statuses it downloads is to edit the queries directly.


Step 6 –Query designer

Query designer screen allows you to view/edit and test the queries used to communicate with your website.

  • Exists – indicates the script is present and is in use
  • Edit button – allows you to open query designer window and edit/run the script seperatly
  • Test – indicates successful or unsuccessful test.

Before you can proceed any further you must click Test All button and ensure all scripts are running correctly.
If you see red cross in the Test column – move your mouse over it and check the error message.

Step 7 – Postal Service Mapping

Here you can map shipping service names on your website to service names in Linnworks. When a customer checks out on your website with a specific shipping method specified, Linnworks will use this mapping table to allocate the order to the service defined in Linnworks.


Step 8 – Payment Method Mapping

You can map payment method defined on your website to payment methods available in Linnworks. When a customer makes a payment on your website using a specific payment method, Linnworks will use this mapping table to allocate the order to the payment methods defined in Linnworks.


Step 9 – Preview orders

This screen allows you to preview the orders that are currently available for download from your website (what orders are downloaded from your website is determined by the status you have selected in the Order Status to download in Step 5). You can view detailed order XML by clicking View Order button.


Step 10 – Save and Exit

Click Save and Exit to add the channel to the integration and exit the wizard.