Third Party Order Platforms: Importing Trade Orders

If you sell coffee through Trade, you can upload a comma-separated values (CSV) file containing your Trade orders. RoasterTools matches each Trade item to one of your product variants and creates orders under a customer you select.

Availability: Trade importing must be enabled for your account. If you do not see Import Trade Orders, contact RoasterTools Support.

Overview

  1. How Trade order matching works
  2. Part 1: Build the matching value from your Trade CSV
  3. Part 2: Add the matching value to your Product CSV
  4. Configure and import Trade orders
  5. Troubleshooting & FAQs

How Trade order matching works

Trade and RoasterTools name the same coffee in different ways, so RoasterTools needs one shared value that identifies a product variant in both systems. You build that value once for each variant, and every import after that uses it.

The full flow has four stages:

  1. Start in the Trade CSV. Every row describes one item that was ordered. Three of its columns describe the product: product_name , size , and grind_type .
  2. Build the matching value. Join those three values with hyphens, in that order, to get a single value such as Ethiopia Halo-12oz-Whole Bean .
  3. Add the value to your Product CSV. Copy that value into a SKU column on the RoasterTools product variant it refers to, then upload the Product CSV.
  4. Import your orders. RoasterTools now recognizes that item in every Trade file you upload and adds it to the order.

This is a one-time setup. You normally map each product variant only once. Once a variant is mapped, later Trade imports match it automatically. You only come back to this setup when you start selling a new product variant, or when Trade changes the way an existing product is named.

Part 1: Build the matching value from your Trade CSV

Start in the Trade file. In this part you only read values and note the result — you do not change the Trade file, and you do not upload it yet.

  1. Download an order CSV (a Trade Batch CSV) from Trade and open it in a spreadsheet.
  2. Find these three columns:
    • product_name
    • size
    • grind_type
  3. Pick a row and read the value in each of those three cells.
  4. Join the values with a hyphen between them, keeping this order: product_name , then size , then grind_type .
  5. If one of those three cells is empty, skip it and join the cells that contain text.
  6. Note the finished value. You paste it into your Product CSV in Part 2.

The three columns you need, as they appear in a Trade export. Your own file contains different products and values.

Use grind_type , not grind . The file contains both columns, and they hold different values. The grind  column holds a short code such as WB , while grind_type  spells the option out, such as Whole . Matching uses grind_type . Building the value from grind  is a common reason an item fails to match.

Matching is exact. Copy each value exactly as it appears in the Trade CSV, including spelling, punctuation, spaces, and capitalization. 12 oz  and 12oz  are two different values, and so are Whole  and whole .

Example

product_name size grind_type Matching value Where it goes
Ethiopia Halo 12oz Whole Bean Ethiopia Halo-12oz-Whole Bean SKU1
Hawthorne House Blend 12 oz Whole Hawthorne House Blend-12 oz-Whole SKU1
Ethiopia Halo 12oz (empty) Ethiopia Halo-12oz SKU1

The first two rows come from different files, which is why one reads 12oz  and the other reads 12 oz . Both are correct, because each one copies its own file exactly. The third row shows an empty grind_type  cell: that cell is skipped, and only the cells containing text are joined.

Part 2: Add the matching value to your Product CSV

Now add the value you built to RoasterTools, so the product variant answers to it. These extra SKU columns are sometimes called alternate SKUs.

  1. Go to Your Name > Settings > Import & Export > Products.
  2. Click Download CSV to download your current Product CSV.
  3. Open the file and find the row for the RoasterTools product variant that the Trade item refers to.
  4. Paste the matching value into that row's SKU1  column. If SKU1  already holds a value, use SKU2  or the next empty SKU column.
  5. Repeat for each Trade product variant you sell.
  6. Save the updated file as a CSV.
  7. Return to Settings > Import & Export > Products and upload the file with Upload CSV.

RoasterTools emails you after the upload to confirm whether it succeeded.

Tips for editing the Product CSV

  • We recommend editing the file in Google Sheets, because some spreadsheet applications change CSV formatting. Be sure to download the finished file as a CSV.
  • Do not make any changes to the first row or the first column in the spreadsheet. This is what matches your changes to the products inside of RoasterTools.
  • You can add more SKU columns (SKU2 , SKU3 , and so on). This is useful when you sell the same variant on several platforms and each platform needs its own matching value.
  • You can delete rows that do not need a SKU change before uploading. It speeds up the upload and makes your change easier to review.
  • Give each matching value to only one product variant. A value that appears on two variants cannot identify either one.

Once a variant is mapped, you do not need to repeat Part 1 and Part 2 for it again.

Configure and import Trade orders

Step 1 — Select a customer

  1. Go to Your Name > Settings > Import & Export > Import Trade Orders.
  2. Search for and select the customer that should receive the imported orders. We recommend creating a customer named Trade Orders.
  3. Confirm the customer's default delivery method and billing and shipping addresses.

Important: All orders in an uploaded Trade file are assigned to the customer selected in the import settings. Imported orders use that customer's default delivery method and billing and shipping addresses.

Step 2 — Choose your import options

  1. Choose how RoasterTools should create the orders:
    • Import as single order — Off: Create a separate RoasterTools order for each Trade order_id .
    • Import as single order — On: Combine the entire uploaded batch into one RoasterTools order.
  2. Choose how RoasterTools should create the line items:
    • Roll up line items — Off: Keep every CSV row as a separate line item.
    • Roll up line items — On: Combine rows with the same matching value and add their quantities together.
  3. Click Update preferences.

Tip: When both options are on, RoasterTools combines the entire batch into one order and combines identical items across that order.

Step 3 — Upload the Trade CSV

  1. Download the order CSV from Trade.
  2. Return to Your Name > Settings > Import & Export > Import Trade Orders.
  3. Select the Trade CSV.
  4. Click Import CSV.

Required CSV headers: Do not rename or remove the following columns from the Trade export.

  • batch_id
  • order_date
  • order_id
  • quantity
  • product_name
  • size
  • grind_type

Having trouble uploading the file? The CSV must be saved using UTF-8 character encoding. Follow How can I fix the UTF-8 error when uploading a CSV? if RoasterTools reports an encoding problem.

What happens next: RoasterTools processes the file in the background. The user who started the import receives email results showing which items matched successfully and which failed. Imported orders appear as Pending or Ready, according to the account's Default Order Status setting.

Troubleshooting & FAQs

What if a product could not be matched?

  1. Find the unmatched value in the completion email.
  2. Compare it with the matching value stored in the SKU columns on the corresponding RoasterTools variant.
  3. Check the most common causes:
    • The value was built from grind  instead of grind_type .
    • The spelling, punctuation, spaces, or capitalization differ between the two files.
    • The variant has no matching value in any SKU column yet.
  4. Correct the value in your Product CSV and upload it before attempting to import the missing items.

What if the file is missing required headers?

  1. Download a new order export from Trade.
  2. Confirm that the required columns listed above are present.
  3. Upload the new file without renaming or deleting columns.

What if RoasterTools says the CSV has already been imported?

RoasterTools uses the Trade batch ID to help prevent duplicate imports. Do not repeatedly upload the original file.

What if only part of an order imported?

Warning: An order can be created with only the items that matched successfully. Do not re-upload the complete original file, because that can duplicate successful items.

  1. Correct the matching value for each failed item.
  2. Keep the original CSV and completion email for reference.
  3. Contact RoasterTools Support at support@roastertools.com for help preparing a partial re-import.
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Related Articles