Installation and Setup

Linnworks is an order management and stock control system that integrates with multiple sale channels like eBay, Amazon, Magento and now, WooCommerce.
Linnworks handles the whole sale channel process from order fulfillment to shipping, stock control and inventory management. Using the WooCommerce Linnworks Integration extension you will take advantage of a powerful sale management system, which will control your store inventory, update orders, send emails, print invoices connect with shipping vendors and many more.

The “WooCommerce Linnworks Integration” is developed and supported by Ivan Andreev | VanboDevelops and not by Linn Systems.
To install properly, please follow this documentation and if there are any problems feel free to contact support at or at [email protected]

WooCommerce Linnworks Integration main features are:

  1. Order Management
    • Automatic synchronization of all orders from WooCommerce. Just pick the order status you want to sync and all orders will be downloaded into the Linnworks system. From there you will be able to print invoices, shipping labels, packaging and much more.
  2. Inventory Management
    • Inventory management allows you to have your whole inventory in one single system. This way you will never oversell your products. Once you sync WooCommerce and Linnworks, any sale downloaded by Linnworks will be automatically reflected in your WooCommerce store and the other way around.
  3. Shipping Management
    • You have many shipping options and need to track each order shipping method? WooCommerce Linnworks Integration allows you to map all your shipping options with Linnworks shipping services. You will automatically know what shipping option the customer chose and take the appropriate action.
    • After the order is processed and shipped it will be updated in the WooCommerce store, at which point a tracking number (if such is assigned) will be emailed to your customer.
    • Shipping Services and Tracking number can be conveniently displayed on the View Order and Track Your Order pages.
  4. Stock Control Notifications
    • WooCommerce Linnworks Integration adds “back in stock” notification, which is automatically sent when new stock is added to an already “out of stock” product.
    • It adds a new “Order Completed” notification, which informs the customer the order is shipped and provides the Shipping and Tracking info.

Before you setup the Linnworks integration there are prerequisites that you should know and meet.

  1. You need a Woo store set up and at least one order placed.
    • The order needs to be in the status that Linnworks will download.
  2. Every Product needs a unique SKU.
    • That is true for all products and variations. Linnworks treats variations as a separate products.
  3. Main variable product does not count in inventory.
    • You should track inventory for each variation in the Variable products. Essentially the main variable product will not count toward the invenroty and could stay unlinked in the Linnworks system.
  1. First please make sure your FTP is transferring file in Binary format. It is not required, but recommended to do so. Here is simple example of how you do it:
    • FileZilla FTP – go to Transfer > Transfer Type > Click Binary.
    • FireFTP – go to Tools > Options… > Downloads/Uploads tab > Binary Mode.
  2. Upload the `woocommerce-linnworks-integration` folder to the `/wp-content/plugins/` directory.
  3. Activate the plugin through the ‘Plugins’ menu in WordPress.

NOTE: all options are set with default values

  • Go to WooCommerce > Settings > Linnworks
Linnworks plugin settings page
  1. In Main Integration Settings
    Main Settings Section
    • Enable Inventory Synchronization
    • Enter a prefix you want to appear in your Order Reference Numbers. This option is important to distinguish selling channels.
    • Pick the order status of the orders Linnworks will download from your store. Recommended: “Processing” is the most appropriate status.
    • Pick the status your orders will be update to, when marked as processed in Linnworks. Recommended: “Completed” is the most appropriate status.
    • Choose if you want to sync shipping and payment services.
  2. In Notifications Settings
    Notification Settings Section
    • Choose if you want to send “out of stock” and “back in stock” notifications
    • Choose if you want to send “order complete” notifications and if you want to leave a note to the customers on the orders.
    • Enable debug mode. Enable this option only to generate information from couple of syncs.
      • IMPORTANT: The debug log can be substantial depending on your store orders. Do not leave it on for a long time.
  3. Generated Queries section:
  4. Save Changes
  1. Choose your Linnworks plan.
  2. Register and account with Linnworks and login
  3. Download Linnworks from your account page and follow the “Installation Instructions” on their website.

See also Linnworks website for their channel setup instructions

  1. Once installed start Linnworks and go to Settings > Channel Integration > Add New Channel.

    Add New Channel
  2. Pick Generic Website from the Dialog box.

    Choose Generic Website
  3. In the Select Website Cart, choose Bespoke website.

    Bespoke Website Type
  4. Enter all fields and Deploy Gateway. IMPORTANT: if you are using only SFTP to access your site, you should visit the Setup Channel using SFTP page. Then skip this step and go to step 5.
    Gateway Deployment Settings
    • FTP Server Path – FTP path to your main WordPress directory ( same level as wp-config.php ). For example: ftp:// DO NOT point to the plugin folder.
    • FTP Username – Your FTP Username you login with
    • FTP Password – Your FTP Password you login with
    • Site URL – The URL where the uploaded gateway can be reached. ( Usually will be )
    • Database server – Your database server name ( same as DB_HOST, in your wp-config.php file )
    • Database name Your database name ( same as DB_NAME, in your wp-config.php file )
    • Database username – Your database username ( same as DB_USER, in your wp-config.php file )
    • Database password – Your database password ( same as DB_PASSWORD, in your wp-config.php file )
  5. In Settings, enter the name of your channel. This name cannot be changed once set.

    Name of Your New Channel
  6. In Query Designer, you will need to paste each query script from your site “Generated Queries” section to the matching script section in the Query Designer.
    Edit Queries
    • Just click on the Edit note and paste the script.

      Paste Queries Here
    • Once you paste all queries from “Generated Queries” section to the Query Designer, click the Test All button.
  7. You can preview your Processing orders in the next step. Remember you should have at least one Processing status order.

    Preview orders
  8. In the last step you will have the chance to Save your channel.

    Save and Exit
  9. When your channel is setup you will see it in the Channel Integration Section.

    Your New Channel

Now that you did setup your Linnworks Integration Channel, you need to deploy our custom script, which will fully integrate WooCommerce with Linnworks.

If you are using version v1.1.2 or lower, please see the Manual Deploy section below. If not, please follow the steps bellow.

  1. Go to WooCommerce > Settings > Linnworks tab > under “Deploy Linnworks API File” section, enter your Linnworks Gateway Password and click Deploy File button. If the deployment is successful, you will see a success message.
    Deploy Custom Gateway Section


  2. Get the Gateway Password from the Query Designer window. Linnworks > Channel Integration > your channel Config > Query Designer > Edit icon of one of the channels > Copy the Gateway Password
  3. Paste the gateway password in the Linnworks Gateway Password field and Deploy File.

    Custom File Deployed
  4. Now you want to check, if the orders are correctly populated. Go to Linnworks > Settings > Channel Integration > click “Config” Button > Click Preview Orders.
  5. In the new window click the Preview button to pull the orders from your store.Then click the magnifying glass to open a details window.

    Pull Orders to Preview
  6. In the window with the orders displayed click on the magnifying glass and scroll down to the OrderItems node. Expand the node and find the items details like ChannelSKU, Cost, ItemTitle. All those should have values in them. If they don’t, make sure you have done the steps above( See Image Below ).
  7. If you see something wrong please repeat step 1, try Manual Deploy, read through the FAQ section, or contact support.
  8. Your integration is now setup. You can sync your orders and match your WC inventory to your Linnworks. Enjoy!
  • Sync Products Inventory
    • Enable if you want to sync Linnworks and your store inventory. The inventory will be controlled from the Linnworks system.
    • IMPORTANT: This option will only allow you to generate the query you will need to sync the inventory. Turning off the option after the inventory was synced will not automatically unsync it, you will need to delete the “UpdateInventory” query from Linnworks system.
  • Order Reference Number Prefix
    • This is the prefix that will be applied to the Linnworks “Reference” field in the order details. It is used also for identifying and updating the orders.
    • IMPORTANT: If you want to change this prefix, you will need to regenerate the SQL queries and re-apply them in Linnworks.
  • Download Order Status
    • Choose what status orders you want to download into the Linnworks system.
    • RECOMMENDED: usually the order status to download would be “Processing”, since this will indicate that the order is paid and the inventory is lowered.
  • Status to Mark Orders after Processed
    • Choose what status the orders to be updated to, after they are processed in Linnworks system.
    • RECOMMENDED: usually this is the “Completed” status, which indicates that the order is packaged and mailed.
  • Map Shipping Services
    • Enable if you want to map the shipping methods to the shipping services in Linnworks.
  • Map Payment Services
    • Enable if you want to map the payment methods to the payment services in Linnworks.
  • Notifications
    • Send “out of stock” notification
      • Notification is send when the product stock is marked as 0. Notification goes to the “Inventory notifications” email set in the WooCommerce installation.
    • Send “back in stock” notification
      • Notification is send when new stock arrived and Linnworks updates the stock level from 0 to a positive value, but more than the “Low stock threshold” inventory set up in WooCommerce. Notification goes to the “Inventory notifications” email set in the WooCommerce installation.
  • Add Tracking Info To
    • ‘View Order’ & ‘Track Your Order’ pages
      • Will show the tracking info on the View Order & Track Your Order pages
    • Leave “Order note” for the customer
      • Leave the customer a note on the order with the Shipping Service and Tracking Number (if applicable).
    • Order ‘Completed’ & Order ‘Processing’ emails
      • Will show the tracking info on the WooCommerce order Completed & order Processing emails
  • Tax Sync
    • Send Order Tax Per Item
      • Send the order items tax with the Linnworks request.
      • If send with the request, Linnworks will use the percentage values that are used in it.
      • If not present in the request, Linnworks will recalculate the tax based on its internal tax settings.
  • Debug Mode
    • Debug mode will generate all requests and responses from Linnworks. Location of the log is in the setting description.
    • IMPORTANT: The debug log can be substantially big depending on your store orders. Do not leave this option ON for a long time.
  • Deploy Linnworks API File
    • Enter below your Linnworks Channel Password and click the “Deploy File” button.
    • IMPORTANT: Do this step only after you setup your Linnworks integration channel. Do NOT perform before you setup Linnworks integration channel.
  • AfterShip Tracking
    • Enable tracking via AfterShip
      • The tracking number and Shipping services will be transferred to the AfterShip meta box.
      • IMPORTANT: Your Shipping Service Tag in Linnworks should match the shipping service tag in AfterShip.
      • Click here to see the the guide to set Linnworks to talk to and work with AfterShip

Please visit this link to view the plugin changelog:  Plugin Changelog

VERY IMPORTANT: Do NOT Permanently Delete any of your products. Trashing a product is good enough. Permanently deleting a product will leave you with a none working Linnworks integration and sometimes a big mess to sort out. If you still did do it, please use the contact form to get help.

  1. I have setup the extension, but the sync fails. What should I do?

    • First go back and make sure you go through the setup checklist
      1. Make sure you have Saved your preferred “Main Integration Settings”, before to copy and paste the Queries in the Linnworks “Query Designer”
      2. Did you filled in and replaced the main linnworks_xml.php file with the one in your extension folder?
      3. Do you have at least one order placed? The order has to be in the status you set Linnworks to download orders from your store.
      4. If you missed something, do it and try the sync again. If you did everything, turn debug mode on and generate a single sync, then contact us for support.
  2. My sync works, but the SKUs of the products look like “WooCommerce-231” (“Order Reference Number Prefix-Product#”) Why is this happening?

    • Make sure you have set the SKU field of all products.
  3. I updated to the new Linnworks version. Are there any more steps I should perform?

    • Yes, usually you need to re-apply the Linnworks Queries. If there are any changes to the Queries, they will not be applied in Linnworks automatically.
  4. I don’t want to use the built-in completed order notifications, I want to use the WC completed order notifications. What should I do?

    • If you want to use only the WC email notifications, when the order is completed, then all you need to do is disable the “Send “order complete” notification email” option.
  5. I followed the integration instructions and everything syncs correctly except the order items. What should I do?

    • Go back to the instructions Step V and redo it. This step is the one that will populate your order contents and export them to Linnworks. If you still have problems, please do the steps from Manual Deploy section.
  6. I tried the queries in the Query Designer and some of them are showing errors? Is this why my integration does not work?

    • No. Some of the queries are populated run time by the software and they cannot be tested in the Linnworks Query Designer. However, make sure that all queries show a green thick, when you click on the “Test All” button.
  7. Update to WooComerce 2.2+ from WooCommerce 2.0/2.1, now my integration does not work. What should I do?

    • You need to save settings and re-apply the new queries in the Linnworks Query Designer. Click here for a detailed guide.
  8. I have many locations with stock for a product, but I need only one location to be synced with my products stock. Can I do that?

    • Yes, you can do that. Go to Settings > Channel Integration > Your channel Config button > in the window check the Sync from specific location checkbox > Click the Location Mapping button and choose the locations you want to sync your product to.Inventory Locations Sync setup
  9. I added SSL to my website and now my integration does not work. What can I do?

    • No worries, since you added SSL to your site, the old “http” site might be redirecting to your new “https” site, so the Linnworks gateway file is no longer accessible. You can fix that by updating the file location in the Linnworks channel. Go to: Linnworks > Settings > Channel Integration > Your channel Config button > at the top of the window you will see Gateway URL field. Amend the Gateway URL to match the new SSL link of your site.

      Amend Gateway URL
      Amend Gateway URL

If you could not deploy the API file through “Deploy Linnworks API File”, you can perform this step manually. Just follow the steps below.

  1. When the integration is done open the “woocommerce-linnworks-integration\linnworks_xml.php” file (in notepad++ or your favorite editor) that came with your WooCommerce Linnworks Integration extension.
    Manual Database Credentials
    • Enter the database details you entered on Step 2 in the fields on top of the file, named: DB_HOST, DB_USER, DB_PASS, DB_NAME and PASSWORD ( Example: define( ‘DB_HOST’, ‘Localhost’ ); )
        • The PASSWORD field you will find by going to Linnworks > Settings > Channel Integration > Click on the Channel “Config” button > Query Designer button > click any of the edit fields > You will see the PASSWORD in the “Gateway Password” field.(See the above image)

  2. After you filled in the appropriate credentials: .
    • Save and upload the file to the “FTP Server path“( your main WP directory ) you entered on Step 2 of the “Integration Instructions” ( Example: ftp:// or WPMainDirectory\linnworks_xml.php )
    • This will overwrite the initial file uploaded by Linnworks. ( Overwrite the with the filled and saved file. )
    Replace the File on Your Server

    As you see on the image above, there is a simple ftp opened (FileZilla):

    • On the left, you have the local directory of your plugin. In the directory you have the custom linnworks_xml.php file.
    • On the right, you have your website main directory. This is where you should have set Linnworks to deploy their linnworks_xml.php file.
    • So all you need to do is replace the one on the right with the one on the left. If the file on the right is in different directory you are doing it wrong.