Marketplace Seller Automation Guide


Introduction


This document will address the requirements for making use of the BooksRun automated Inventory and Order processing systems.

Order and Confirmation delivery is done via FTP (ftp.booksrun.com) with credentials provided by BooksRun after your approval. Using this method, multiple orders are combined into a single text file and Retrieved by the seller via FTP. A seller then sends a text file back to BooksRun that includes confirmations and cancellations. The text Confirmation file is then processed by BooksRun and the status of the orders is updated. This document will address the requirements for making use of the FTP method for BooksRun Automated Order Processing.

All the dates in this guide, as well as the dates in the seller panel and buyer panel belong to Eastern Time Zone.


Inventory


File placement

Inventory files must be placed in the following directory:

ftp.booksrun.com/Inventory

File naming

You must be consistent and follow certain conventions in the way you name the inventory files you provide.

Below we describe our naming conventions:

(marketUserName)_(timestamp)(replacementType)(fileExtension)
  • marketUserName - your seller name on BooksRun

  • timestamp

    • YYMMDD - for daily uploads
    • _YYMMDDHHMM - for multiple uploads a day
  • replacement type

    • ".part" for partial replacement and partial updates
    • ".full" or ".purge" for purge and replace
    • If left empty a partial replacement or partial update is assumed.
  • file extensions

    • ".csv" - comma ',' separated fields
    • ".txt" - tab '/t' separated fields
    • If left empty or unknown, file is treated like a ".csv"

Use the following as a guide:

File Naming Convention Example Comments
membername_YYMMDD.part.csv bookworld_040916.part.csv This is a partial upload file for Sept. 16, 2004.
membername_YYMMDD_HHMM.part.csv bookworld_040901_2145.part.csv This is a partial upload file for Sept. 1, 2004, 9:45pm.
membername_YYMMDD.full.csv bookworld_040901.full.csv This is a full upload file for Sept. 1, 2004.
membername_YYMMDD_HHMM.full.csv bookworld_040815_2145.full.csv This is a full upload file for Aug. 15, 2004, 9:45 p.m.

If you provide just one inventory update file per day, you should include the date in your file name. If you provide multiple updates in a day, you should include a time stamp. Note that embedded spaces within a filename are not acceptable. Separate values within the filename with an underscore "_" character as in the examples above.

Full Replacements must include ".full" or ".purge" in the file name and we strongly suggest including ".part" in Partial Replacements in the filename. If nothing is specified we assume a Partial Replacements.

If there is no file extension in the file name comma delimited is assumed.

File example

add-modify-delete isbn13 sku price quantity item-condition item-note
A 9780471749554 12345 17.99 15 Like New Book is used and in great shape
Download inventory file example: inventory.txt

Data format

Field Name Data Type Max Field Length, Max Value Example Notes
add-modify-delete Text 1 A Possible values: A, M, D
isbn13 Text 13 9780471749554 ISBN10 is supported too (auto translated to ISBN13)
sku Text 40 12345 Must be unique
price Number 20000000 14 or $14.00 or $14
quantity Number 100000 15
item-condition Text Like New Required Values: New, Like New, Very Good, Good, Acceptable
item-note Text 2048 Still in shrink wrap! Displays with your listing

Additional formats

Other supported inventory formats:
  • Amazon tab separated format
  • HomeBase 2.x format
  • UIEE format

Orders


File placement

Order files are generated in the following directory:

ftp.booksrun.com/Orders

Data format

Data format is the same as Amazon Fulfillment Report File Format

Field Name Data Type Example Notes
payment-status Text paid_ship_now Should be paid_ship_now always
order-id Number 12345 Order ID
order-item_id Number 12 Order item ID
payments-date Date 2019-02-23 04:22:37 Date the order was paid
product-id Text 9780134093413 ISBN13
item-name Text Campbell Biology (11th Edition)
listing-id
sku Text 12345
price Number 17.99 Total of item price and shipping compensation
shipping-fee
quantity-purchased Number 3 Quantity of items ordered
purchase-date Date 2019-02-23 04:22:37 Date the order was placed
buyer-email Text buyer@gmail.com
buyer-name Text John Doe
recipient-name Text John Doe
ship-address-1 Text 8 West Main
ship-address-2 Text Apt B
ship-city Text Albany
ship-state Text NY
ship-zip Text 14063
ship-country Text US
ship-method Text standard Possible values: standard, expedited

File example

Download orders file example: orders.csv


Orders confirmation


File placement

Confirmation files must be placed in the following directory:

ftp.booksrun.com/Confirm

File example

ORDER_ID ITEM_ID ORDER_STATUS REPLY TRACKING_ID TRACKING_SOURCE
1 2 Confirm OK 783057949206 Fedex
1 3 Cancel Out of stock
Download confirmation file example: confirm.csv

Data format

Field Name Data Type Max Field Length Example Notes
ORDER_ID Number 10 1
ITEM_ID Number 10 2
ORDER_STATUS Text 40 Confirm Must be Cancel or Confirm
REPLY Text 255 Out of stock Shown to customer (or should be)
TRACKING_ID Text 255 15
TRACKING_SOURCE Text 12 Fedex

Support of 3rd party inventory management systems


The Art of Books

ArtOfBooks integration can be configured with Custom Venues feature.

In ArtOfBooks dashboard Go to "Settings" > "Venue settings" and use the following settings for any free Custom Venue slot:

Setting Value
Custom Venue X FTP Display Name Any meaningful name (e.g. BooksRun, booksrun.com, BooksRun Marketplace, etc.)
SFTP Unchecked
Custom Venue X FTP Host ftp.booksrun.com
Custom Venue X FTP Username Your FTP username on BooksRun Marketplace
Password Your FTP password on BooksRun Marketplace
Password (Re-enter) Your FTP password on BooksRun Marketplace
Format Amazon Tab
Custom Venue X FTP Directory ArtOfBooks
Pull Orders
Active

Monsoon Inc.

Monsoon integration is fully supported.

Ask Monsoon support for assistance.

Updated on August 9th, 2023