Can I upload my items in bulk?

When one-item-at-a-time inventory management becomes tedious, sellers can take advantage of the Bulk Upload feature. The bulk uploader reads a plain text file containing information about items to be added, deleted, or otherwise updated and adds, deletes, or updates the specified items accordingly. However, In order for the Bulk Upload to be executed successfully, the text file must be formatted in a very specific way.

This article describes how to correctly format your Bulk Upload file and explains the steps you must take to carry out a Bulk Upload. If you already have experience working with csv files, consider skipping the Introduction and going straight to the Specification.

INTRODUCTION

A Bulk Upload file is a lot like a spreadsheet. Every line of text in the file corresponds to a row in a spreadsheet, and every row contains instructions to add, delete, or otherwise update one item. Similarly, every column corresponds to an item field such as Department, Category, Price, etc. However, since the Bulk Upload file is a plain text file, we need a way to mark where one column ends and another begins, or more specifically, where one cell ends and another begins. For example, we have already mentioned that the end of a line in a Bulk Upload file corresponds to the end of a spreadsheet-row, but how can we mark the end of a column/cell? For the GoAntiques bulk uploader, the column/cell/field delimiter is the comma character (,). When the bulk uploader scans a Bulk Upload file and sees a comma, it know that it has reached the end of a cell, just as it knows that it has reached the end of a row when it encounters then end of a line in the text file. Thus, we say that the Bulk Upload file is a comma-delimited text file, or more commonly, a csv (for "comma separated values") file.

There is one caveat that must be mentioned here. Since the bulk uploader interprets every comma to signify the end of a column/cell/field, the Bulk Upload file must contain commas only where one wishes to indicate the same. But what if a field itself contains one or more commas? To indicate that a comma is to be interpreted literally by the bulk uploader (and not as a field delimiter), the entire field in which the comma(s) is contained must be enclosed by a double quotation mark (") at both ends. Thus, we say that the double quotation mark is the text delimiter, as opposed to the comma, which is the field delimiter. Moreover, fields that already contain double quotation marks must themselves be enclosed in double quotation marks, and the quotation marks contained within the fields must be "escaped" by another quotation mark. That is, every double quotation mark that appears within a field must be coded by a double double quotation mark, like "". In other words, the bulk upload will interpret a single double quotation (") mark as a text delimiter, but it will interpret a double double quotation ("") mark as a single quotation mark ("). For example, if you want a particular item's Description field to look like:

This "platinum" ring is actually platinum-coated nickel.

then its entry in the Bulk Upload file must look like this:

"This ""platinum"" ring is actually platinum-coated nickel."

And if for some reason you wanted the Description field to look literally like the latter example above, the corresponding field in the Bulk Upload file would have to look like so:

"""This """"platinum"""" ring is actually platinum-coated nickel."""

It may seem, therefore, that properly formatting a file for Bulk Upload would require a great amount of tedious work and valuable time. Fortunately, most spreadsheet applications can automatically format your file for you--the analogy between a Bulk Upload file (correctly formatted) and a spreadsheet is actually more than an explanatory aid. In fact, most Bulk Upload files begin as spreadsheets for spreadsheet applications like Microsoft Word or LibreOffice Calc and are turned into correctly formatted Bulk Upload files by those applications' Export to csv  or Save as csv feature, which turns the spreadsheet into a plain text file with user-specified field delimiters and text delimiters. (In our case, we would tell the spreadsheet application to use a comma for the field delimiter and a double quotation mark for the text delimiter.) This feature of most spreadsheet applications makes formatting a Bulk Upload file so easy that GoAntiques recommends keeping inventory in this way, that is, keeping inventory organized in a spreadsheet file for a program like Microsoft Word or LibreOffice Calc. Conveniently, we have found over the years that many, if not most, sellers already keep track of their inventory in a spreadsheet file, or at least in a file for a program capable of exporting to a spreadsheet or csv text file. If you already list and record your inventory in a spreadsheet file, even if it is not yet formatted specifically for GoAntiques Bulk Upload, generating a correctly formatted Bulk Upload file will be significantly easier.

In the following sections, the format of the Bulk Upload file will be explained in detail. But for now, let us take a look at a sample spreadsheet that could be used (exported) to create a Bulk Upload file.

Action	Category	Subcategory	Department	Title	Status	Desc	...	RefNum	...	Price
add	Furniture & Furnishings		Antiques	Old Couch	For Sale	...		003a		800
add	Jewelry		Antiques	Gold Ring	For Sale	...		101c		800
delete	Jewelry	Women's	Collectibles	Beaded Bracelet	For Sale	...		101d		27.99
add	Fine Art		Antiques	Picaso's Igor Stravinsky	Inactive	...		057a		9999

The top row contains the column headers. These are the verbatim names of item fields, except that the first column ("Action") tells the bulk uploader what to do with the row's item (as specified by the RefNum field, or "reference number"). So for example, the fourth row tells the bulk uploader to delete the item with reference number 101d, while the fifth row tells it to add item 057a with whatever text is contained in the other cells in that row--let us pretend that item 057a already exists, in which case, add means the same as "update". In the above example, columns that have ... as their header simply indicate that one or more columns have been ellipsed, for sake of example. Notice also that some cells are blank. This is because certain fields, such as Subcategory, are optional and require no definition, though if one is given, it must be valid. For a thorough description of the different fields, as well as an enumeration of which ones are required, see What should I enter in each inventory field?.

BULK UPLOAD FILE FORMAT SPECIFICATION

What follows is a point-by-point definition of the Bulk Upload file format specification.

• Files must be plain text encoded in UTF-8.
  

• The field delimiter is the comma (,). The text delimiter is the double quotation mark ("). In accordance with traditional csv file-format standards, only fields that contain one of the delimiters must be delimited by the text delimiter. Within such fields, the double quotation mark must be represented with a double double quotation mark ("") so as to avoid confusion with the delimiter itself. (The Export to csv or Save as csv features of most spreadsheet applications will automatically take care of these details as long as the correct delimiters are specified.)
  

• Reference numbers, category and subcategory names, department names, etc. must be spelled out exactly as they appear on the Edit Listing and Create Listing pages. For example, "ground" is not a valid entry for the ShippingType field, whereas "Ground" is.
  

• The first line of the file must contain a complete listing of the item fields (separated by commas) in the following order: Action, Category, Subcategory, Department, Title, Status, Desc, Type, RefNum, CtryOrig, Style, Color, Condition, YearMade, Price, Material, Maker, ImageFile, ImageFile2, ImageFile3, ImageFile4, ImageFile5, ImageFile6, ImageFile7, ImageFile8, ShippingType, ShippingCost, Quantity, Height, Width, Depth, Weight, SellerID. These entries must be spelled precisely as they appear here, case and all.

• Some fields do not require any values, and some require one value from a limited set of possible values. For a description of all fields and their possible values, see What should I enter in each inventory field?. Fields that do not require a value (e.g. ImageFile2, ImageFile3, etc.) may be left blank, but all columns must be present regardless.
  

• Every line other than the first corresponds to the item specified by the RefNum (reference number) field. If no reference number is supplied for a given line, no action will be taken for the item supposed to correspond to that line.

• Every line's Action field specifies the action to be taken with regard to that line's item.

• Items (lines) marked add tell the uploader to add those items with the information provided in the other fields.

• Items marked delete tell the uploader to delete the those items.

• Lines marked add for items that already exist will cause those items to be updated.

• The ImageFile fields must contain valid http or ftp urls that point to images, such as http://www.mywebsite.com/imagename.jpg. These images will be downloaded to the GoAntiques servers, so subsequent removal of the specified urls will not affect the images as seen on goantiques.com.

• For a description of all other fields and their possible values, see What should I enter in each inventory field?.

RUNNING A BULK UPLOAD

Once you have a correctly formatted Bulk Upload file, you can run a Bulk Upload by clicking the Bulk Upload link on your Dashboard. Enter your file in the Batch Items field, and click Upload. You will be notified of successful or unsuccessful file transfer, but the Bulk Upload itself will not occur immediately.

Once the Bulk Upload has finished, you can return to the Bulk Upload page and view the status of your upload. If the status indicates that an error occurred, click on the status to view which entries caused the error, and consider correcting it and re-uploading. A status of "Success With Errors" means that at least one item was uploaded/updated successfully, in which case the error report will contain an explanation on why the other items failed to upload.