CSV Channel Setup

Overview

CSV File integration is a useful way to import orders from platforms Tradebox doesn't have an API connection with. Once a CSV channel is created, it's normally possible to completely automate the order download process.

CSV channels are used both for marketplaces with which we're familiar and have been partnered for several years and for bespoke connections to systems we haven't dealt with before. That's part of the beauty of CSV; it's a universal standard for allowing different systems to share information.

This article describes CSV channel setup, which applies to Linnworks, Magento v2, Opencart or Romancart. For further information specific to each of those integrations, click the marketplace name. For Amazon, eBay, Magento v1, Bigcommerce, ekmPowershop, WooCommerce or Shopify, instead see their appropriate page on the Channel Integration Guides section.

This article also describes CSV channel setup for bespoke/custom channels; basically, any marketplace or webstore not mentioned above. If you're setting up a custom channel, you'll first need to check that your marketplace can export the orders in a CSV format that meets Tradebox's file specifications. An in-depth explanation of the required CSV file format, including a sample file, is available within the CSV order specification article. If you're unsure about exporting data from your webstore and whether this is a native function or will need to be added, check with your web developer. Understanding the properties and format of the data in the file is key to making this integration as smooth as possible. If you have questions about the integration or need any assistance, contact Tradebox Support.

Note - to keep the integration working smoothly, it's really important that all the files going through a CSV channel are consistent; having the same data in the same order every time.

Once you've been through this article and created your CSV channel, we recommend reading the CSV Channel Configuration Guide that explains the configuration settings in the channel after it has been created.

Preparation

• You will need to download and save an example of your CSV order file locally, with orders in it, to be used by Tradebox during the setup. Make sure this file isn't open in Excel or any other program.
  • Part of the channel setup will involve choosing how information for more complex orders is presented. If you're generating your own file of test orders, you should make sure you've got at least one example of each of the following:
    • Multi-item orders
    • Orders with discount (where applicable)
    • Any marketplaces, statuses, filters or payment methods you wish Tradebox to use to differentiate orders.
• If you are publishing your CSV file to an FTP server you'll need the FTP login credentials to hand.

 

Creating the Sales Channel

Launch the New Sales Channel Wizard via Channels > New.

Sales Channel Details

Choose file import as your Marketplace. Click next.

Enter a name for the Sales Channel (max. 50 characters). This is a label purely for you to identify the channel and can be amended at any time.

Choose your currency from the drop-down. Each channel in Tradebox can only import sales in a single currency. If you sell in multiple currencies you will need to create a different channel in Tradebox for each currency.

Note - if you're setting up multiple channels to handle different currencies, it's fine to use a single import file containing orders in multiple currencies, so long as the file contains the 3-letter currency code on every line. Per-sales channel, orders that don't match the channel's currency will be ignored.

 

FTP Download (optional)

Tradebox can read CSV files from your PC or local network, or from an FTP server. If using FTP, enter the server address along with a username and password that Tradebox will use to access your FTP.

The server address should specify the exact location where your files will be created including any subdirectories (in our example, Tradebox is looking for a subfolder called 'CSV' on the root of the FTP and will download a file called orders.csv if it's present in this directory). Your address should always start with ftp:// or ftps:// or sftp:// depending on the security protocol required to connect.

The file name field is used to specify the name of the CSV file you're downloading from the FTP if there are other files in the folder. If the only files on the FTP are your order files for Tradebox, or the name of the order file won't be static, you can use * to tell Tradebox to download all files.

The connection is active option should only be ticked if you require an Active FTP connection (most FTP's don't) - it refers to the connection type rather than meaning on/off or similar. If you are unsure whether your FTP requires Active or Passive connection, check with your FTP provider.

The delete file from server tick box is unticked by default. If ticked, this will delete order files from your FTP location once Tradebox has processed the file. If you have orders in multiple currencies in the same CSV file, you should leave this unticked as Tradebox will need to process the same file multiple times across different channels. Deleting files from the FTP after they've been read isn't necessary for Tradebox; each sales channel will check each order to see if it has already been presented on an earlier download, so there's no risk in having the same file downloaded and processed multiple times.

Click next to continue.

Import File Details

The Import File Details screen is where you'll let Tradebox know how to read the information in your file.

Column Delimiter refers to how your file presents a break within fields; e.g. where does the 'date' information end and the 'order id' information start. Most CSV files are comma-delimited, though Tradebox can also handle tab-delimited or semi-colon-delimited files.

Date Format: choose the format that represents the dates in your file.

Total Shipping Cost dictates how Tradebox calculates the carriage in your file for multi-line orders; is that a Duplicated Cost Across Lines, or an Individual Cost Per Line. See how is shipping cost displayed? for more details.

Price Is shows how the product price is displayed in the file. These can be either the unit price or a line price (the total price of units on the line; a line total that also includes carriage or other charges is not supported). This option decides whether Tradebox multiplies the Unit Price by the quantity to get the line total, or divides the Line Price by quantity to get the price of one unit.

Other Amount is usually an additional service that is charged for, like gift wrapping or shipping insurance. This option shows how the Other Amount is displayed against each item in the file. The options are Duplicated Cost Across Lines or Individual Cost Per Line and follows the same logic as shipping cost.

The Import File Has Column Headers tick box should be ticked if the first row in your CSV file is a header/column label row. If the first row is your first order, untick this box. Files with or without headers are supported, in general we'd advise using files with headers as this will make it easier for you to check the information in the file in the event of any discrepancies.

Note- in either instance Tradebox will only read the file if there are no blank rows between orders, or between the header row and the first order line.

Next, you’ll need to choose an example of the import file to allow Tradebox to map the fields. Click the […] button > browse to and select your file and choose Open. 

Then click next.

Import File Format

This grid displays the available Tradebox fields in the first column and which fields in the CSV file they are mapped to. The fields displayed in red are mandatory; they either need to be mapped to the file or set to a fixed value. When you click into a field in the grid, an explanation of the field will be provided in the field description at the bottom of the screen. 

To add a mapping click into the adjacent field in the column in file column. This is populated with a list of column headers from the file you chose in the previous step. If your file doesn't have column headers the field will be populated with the column letters; A,B,C,D etc. You might find Tradebox has auto-detected some or all of your fields based on the column headers, though you can amend those mappings if they're incorrect.

Your file may not contain all of the fields Tradebox can read. It's fine to leave non-mandatory fields blank. Alternatively, you may wish to set any field to a fixed value which will then be used against every order handled through this sales channel. If your file doesn't contain any of the mandatory fields Tradebox expects, you can also set them to fixed values (with the exceptions of order date and order ID which must be read from the file). Depending on the field, setting to a fixed value may impact on the functionality of Tradebox and your ability to report constructively on sales, so where possible it's better to read information from the file. To set a fixed value, leave the dropdown column in file blank, click on the fixed value column against that field and type in the fixed value you wish to use. For example, if your order file doesn't contain a payment method, you could set the fixed value of 'Default'; or if this sales channel only handles orders paid via PayPal you could alternatively set the fixed value of 'Paypal'. 

Sometimes the information that represents one field in Tradebox may be presented as multiple fields in the file. For example, if your file carried the buyer's first name (John) and last name (Smith) separately you'd likely want to amalgamate this into Tradebox's billing name field as John Smith. To accommodate this there are 2 additional columns; add column 2 and add column 3. To amalgamate text file fields, you'd map the first field to column in file, the second to add column 2 and the third to add column 3 where applicable, e.g.

Tradebox Field	Column in File	Add Column 2
Billing Name	First Name	Last Name

Where the field represents a monetary value, adding columns will take the total of the columns mapped. The common example is to calculate gross prices, which are a requirement of the software. If the CSV file contains the net unit price (exclusive of VAT) and the amount of vat per unit in separate fields this feature can be used to combine the 2 prices to calculate the gross price, e.g.

Tradebox Field	Column in File	Add Column 2
Product Price (Gross)	Unit_Price_Net	Unit_VAT_Amount

The Template CSV article provides guidance on all of the available Tradebox fields, how the data needs to be configured in the file and how this data is used in Tradebox. Field mappings can be amended at any time after the channel is created via Channels > Edit > Import File tab.

Once you've mapped all your fields, click Next.

Sales Sources

Tradebox can include or ignore orders based on the marketplace/platform they were sold through, if this information is included in the file. Typically this is where users want to apply different settings, or report per-marketplace. This is based on the Tradebox field sales source, if it was mapped in the previous screen. If you've mapped a sales source from your file, Tradebox will display a list of every unique entry that was present in your example file. The list of sales sources can be amended, and additional sales sources added, in the sales channel details screen after the channel has been created.

Tick the entries you wish to download and choose Next. 

Order Statuses

If the CSV file has a column containing an order status and this column has been mapped to the Tradebox order status field, the wizard will show all of the unique order statuses in the file with the option to choose which statuses to download. Tick the entries you wish to download.

After the setup wizard is completed you'll need to do a little additional configuration to map the order statuses in the file to Tradebox's internal order statuses. This is done in the Statuses tab of the sales channel; here you can also add order statuses that may not have been in the example file and select which order statuses you wish to allow to be posted to your accounts package (where applicable). If you are manually adding a status, please bear in mind that these are case sensitive and must be added exactly as they'll appear in your file.

Click Next. 

Discount Type

The discount type allows the user to choose between a discount type of Order, Line or None. An Order discount setting expects the discount to be populated on every line of the order; this will be added as a negative item line following the last item on the order within Tradebox. If you're integrating with Sage Accounts, the discount amount will be broken down pro-rata across the items on the order.
A Line discount setting expects the discount column in the file to be populated with a value for any items that are discounted, and any other items to have this column populated as 0. A discount setting of None effectively disables discounts through this channel; this should be used where no discounts apply, or where the prices in the file are already presented at the discounted price.

Note - a Linnworks file generated using the script in our Linnworks Setup guide will use an Order discount.

This option can be amended at any time in the sales channel details screen of an existing channel.

Product Details

This section only applies where your stock control method is set to Tradebox and will be hidden if not applicable.

The map existing product records option will let Tradebox know to expect an exact match of marketplace SKUs to the products already in Tradebox's product list. Tick this if you've already imported your products to Tradebox and your marketplace SKU's match the list in Tradebox.

The import product details option allows you to import a CSV file containing product details. This is a quick way to batch-create product records in Tradebox that match the list of products on your marketplace, rather than creating these ad-hoc as each product is sold for the first time. Click the […] button > browse to and select your file > open. Click here for the expected file structure and an example file.

Click finish to complete the wizard. If you've chosen to integrate Tradebox with your accounts package, you'll be prompted to create an accounts link, which you can do now or come back to later.

Importing orders

Before you can commence downloading orders you need to ensure that:

• The order statuses in the file have been mapped to Tradebox's internal order statuses
• The CSV file has been placed in the In folder (if you've told Tradebox to use an FTP server during channel setup, this should happen automatically)

Folders

As Tradebox creates the channel, it will automatically create In and Out folders for order reports within the Tradebox data folder. You can either use these default folders or create your own and direct Tradebox to use them. To view the folders go to channels > edit > details. As a file is placed in the In folder, Tradebox will automatically read it and import any orders that meet the import criteria, then pass the file to the Out folder. You can see the progress of order imports in the Logs screen.

Custom Folders (optional)

To redirect the In and Out folders, use the browse icon  to navigate to your folders and click OK, then Save in the channel. Note that these folders need to be unique to each channel and not used for anything apart from CSV order files for Tradebox to read.

Default Folders

The open folder icon  will open the default folders in a file browser. If you’re manually downloading order reports (rather than using an FTP), you’ll need to familiarise yourself with the location of your In and Out folders; we recommend making a shortcut to these on the desktop of the PC(s) where you run Tradebox. For network users, these need to be locations that all users can read/write to (the same should be true of your Tradebox data folder; as the default in/out folders are created inside the data folder it's still fine to use these over a network).

Once the Sales Channel wizard is complete you can configure additional channel settings. See the CSV Channel Configuration article for a detailed explanation of all the options in a CSV channel.