Third Party Order Platforms: Importing Bean Box Orders

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

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

Overview

  1. How Bean Box order matching works
  2. Before your first import
  3. Part 1: Build the matching value from your Bean Box CSV
  4. Part 2: Add the matching value to your Product CSV
  5. Configure your Bean Box import
  6. Import your Bean Box orders
  7. Troubleshooting & FAQs

How Bean Box order matching works

Bean Box 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 Bean Box 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 SKU1 or SKU2 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 Bean Box 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 Bean Box imports match it automatically. You only come back to this setup when you start selling a new product variant, or when Bean Box changes the way an existing product is named.

If no items match, the order cannot be created. An import that reports Line items can't be blank means none of the items in that order matched a product variant. Complete Part 1 and Part 2 below for the products in the file, then import again.

Before your first import

Before you begin, make sure your Bean Box products already exist as variants in RoasterTools. You will also need a RoasterTools customer for the imported orders.

Create or select a Bean Box customer

  1. Go to Sales > Customers.
  2. Create a customer for your Bean Box orders if one does not already exist. We recommend naming it Bean Box Orders.
  3. Confirm the customer's default delivery method and billing and shipping addresses.
  4. Save the customer.

Important: All orders in an uploaded Bean Box 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. Recipient address columns in the Bean Box file do not create separate RoasterTools customers or addresses.

Part 1: Build the matching value from your Bean Box CSV

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

  1. Download an order CSV from Bean Box 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 columns you need, as they appear in a platform export. Note that grind  and grind_type  are two separate columns. 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  or GR , while grind_type  spells the option out, such as Whole  or Ground . 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 Bean Box 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
Colombia Nariño 12oz Ground Colombia Nariño-12oz-Ground SKU1
Ethiopia Halo 12oz (empty) Ethiopia Halo-12oz SKU1

The third row shows an empty grind_type  cell: that cell is skipped, and only the cells containing text are joined. Copy the value in the Matching value column exactly, including the hyphens and any spaces inside the words.

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 Bean Box 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 Bean Box 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 your Bean Box import settings

  1. Go to Your Name > Settings > Import & Export.
  2. Select Import Bean Box Orders.
  3. Search for and select the customer that should receive the imported orders.
  4. Choose how RoasterTools should create the orders:
    • Import as single order — Off: Create a separate RoasterTools order for each Bean Box order_id .
    • Import as single order — On: Combine the entire uploaded batch into one RoasterTools order.
  5. 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.
  6. Click Update preferences.

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

Import your Bean Box orders

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

Required CSV headers: Do not rename or remove the following columns from the Bean Box 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 SKU1 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 import fails with "Line items can't be blank"?

None of the items in that order matched a product variant, so there was nothing to put on the order. This is normal before the setup in Part 1 and Part 2 is complete.

  1. Open your Product CSV and confirm the SKU1  column contains matching values for the products in the file. An empty SKU1  column on every row means the setup has not been done yet.
  2. Build the matching value for each product using Part 1.
  3. Add the values to your Product CSV and upload it using Part 2.
  4. Import the Bean Box file again.

What if the file is missing required headers?

  1. Download a new order export from Bean Box.
  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 Bean Box 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.