Item CSV Upload Fields
Complete reference for every column accepted in bulk CSV uploads — field names, aliases, requirements, and example values.
Choose a CSV type when uploading — the system expects different columns depending on your goal
Always download the latest template from the admin — column headers must match exactly. LotName works. lotname or Lot Name (with a space) will fail silently. Use the Update Only checkbox to update existing items without creating new records — only columns you include are updated; omitted columns are left untouched.
How to use this reference
Before diving into the field tables, a few things that answer the questions that come up every time.
Item intake upload — adds new items to a consignment from a spreadsheet. This is the type this guide primarily covers. Navigate to Consignments › [consignment] › Items tab › Upload Items via CSV.
Update Only upload — modifies existing item records without creating new ones. Check the Update Only checkbox on the upload screen. Any columns you omit are left untouched; only the columns you include are updated. Use this for bulk catalog edits after intake is complete.
Post-Sale data upload — imports winning bidder data from LiveAuctioneers or Invaluable after an auction closes. Covered in the Third-Party Import module of the User Manual, not in this guide.
Every item must belong to a consignment — you cannot upload items without one. There are three ways to tell the CSV where items should land:
- ConsignorEmail — supply the email address on the consignor's profile. If no open consignment exists for that consignor yet, the system will auto-create one using the consignor's default commission rule. If a consignment already exists, items route to the most recently created open one.
- ConsignorID — the system-generated numeric ID on the consignor record (visible in the URL when viewing the consignor profile).
- ConsignmentId — the system-generated numeric ID of a specific consignment (visible in the URL when viewing the consignment). Use this when a consignor has multiple open consignments and you need to target a specific one.
If none of these columns are present, items land in whichever consignment you were viewing when you initiated the upload. For most migrations, ConsignorEmail is the most convenient — one column handles consignor lookup and consignment creation in one step.
- Case-sensitive headers — column names must match the template exactly.
LotNameworks;lotnameorLot Name(with a space) will cause a silent failure where the upload appears to succeed but items don't appear. Always download a fresh template from the upload screen rather than retyping headers manually. - Duplicate lot numbers with Update Only — if your CSV includes a
LotNumbercolumn and multiple rows share the same lot number, the update will throw 200+ duplicate-number warnings. Either ensure each lot number is unique or omit theLotNumbercolumn entirely for intake uploads (lot numbers are assigned separately at the lot assignment stage). - HTML tags in description fields — if you're exporting descriptions from another system, they may include HTML formatting tags (
<p>,<b>,<br>, etc.). These tags will appear as visible text on the published lot page. Clean the HTML before uploading — loading the CSV into Google Sheets and using a formula to strip HTML is the fastest approach. - File format — save as
.csv, not.xlsx. Excel's.xlsxformat is not accepted. If your CSV opens in Excel and you resave it, check the extension hasn't changed. - StartingBid when uploading to an auction —
StartingBidis optional when uploading to a consignment, but required if you're uploading directly into an auction. Items without a starting bid cannot be published.
1 · Core Item & Auction Details
The absolute fundamentals for identifying your lots.
| Field Name | Required? | Description | Example Value |
|---|---|---|---|
|
LotNumber
also:
Lot LotNum |
Conditional |
The unique number for the lot within its auction. Must be numeric — no letters.
Required if loading items to an auction or updating lot numbers via CSV. Not required if loading items to a consignment. |
101 |
|
LotNumberExtension
also:
Extension LotNumExt |
Optional | A letter suffix that combines with LotNumber to create extended lot references such as 1A, 2B. The number goes in LotNumber, the letter goes here. Used to insert a lot between existing lot numbers without renumbering. |
A |
|
LotName
also:
Title |
Yes | The name or title of the lot. The only field required for all upload types. | Oil Painting by John Doe |
| ReferenceNumber | Optional | Your internal reference or stock number for the item. Appears on barcode labels. | STK-4821 |
| LotImage | Optional |
Pulls images and uploads them via hosted image URLs. Separate multiple images with a pipe character |.
Can also be used to set expected local filenames for images loaded in bulk using 'Filename (from CSV)'.
|
http://ex.com/img1.jpg|img2.jpgimage1.jpg|image2.jpg |
| Video URL | Optional | A link to a video of the item, e.g. on YouTube or Vimeo. | https://youtube.com/watch?v=example |
| Featured | Optional | Set to 1 to mark as a Featured Lot, 0 to un-feature. |
1 |
| Link | System | Auto-generated on export. The public URL to the lot. Do not include in upload files. | — auto — |
| ExportedImgs | System | Auto-generated on export. A list of image URLs for the lot. Do not include in upload files. | — auto — |
2 · Descriptive Information
Where you add the detail, color, and provenance.
| Field Name | Required? | Description | Example Value |
|---|---|---|---|
|
LotDescription
also:
Description |
Optional | Full detailed description. Supports basic HTML for formatting. | Oil on canvas, signed. 24x36 in. |
| Category | Optional | Must match an existing category exactly. Separate multiple categories with a semicolon ;. |
Fine Art;Paintings |
| Tags | Optional | Comma-separated keywords to help bidders find the item via search. | modern, abstract, landscape |
| Height / Width / Length | Optional | Physical dimensions of the item. Add separate columns for each dimension. | 24 / 36 / 2 |
| DimensionUnit | Optional | Unit for the dimensions provided. | in |
| Weight | Optional | The item's weight as a numeric value. | 10.5 |
| WeightUnit | Optional | The unit for the weight provided. | lbs |
| Provenance | Optional | The item's history of ownership. | Private Collection, New York |
|
Condition
also:
Condition Report |
Optional | A detailed description of the item's physical condition. | Excellent condition, no damage. |
| ConditionAttachment | Optional | A URL to a PDF condition report for the item. | https://example.com/report.pdf |
| Attribute:[Name] | Optional | Create a dedicated column per attribute — the column header defines the attribute name and the cell value is assigned automatically. | Column header: Attribute:MediumValue: Watercolor |
3 · Pricing, Estimates & Bidding
All numeric values — no currency symbols.
All pricing fields must be plain numbers. Do not include $, ,, or any other currency formatting. All values must be greater than 1.
| Field Name | Required? | Description | Example Value |
|---|---|---|---|
|
StartingBid
also:
StartPrice |
Yes | The opening bid amount. Required when publishing items to an auction. Numeric only — must be greater than 1. | 500 |
|
LowEstimate
also:
low_est LoEst |
Optional | The lower end of the estimated price range. Numeric only. Must be greater than 1. | 1000 |
|
HighEstimate
also:
high_est HiEst |
Optional | The higher end of the estimated price range. Numeric only. Must be greater than 1. | 2000 |
|
ReservePrice
also:
Reserve |
Optional | The confidential minimum price for the item to sell. Shown to the auctioneer only — never visible to bidders. Numeric only. Must be greater than 1. | 900 |
|
BuyNowPrice
also:
Price |
Conditional | The fixed Buy Now price. Required for Buy Now events. Numeric only. | 2500 |
| Cost | Optional | What the auction house paid for the item — for internal P&L tracking only. Not visible to bidders or consignors. | 750 |
4 · Inventory & Consignment
For those using the full inventory management features.
Combinations of the consignor and consignment fields below allow for exact mapping to specific existing records. If a consignor exists but has no matching consignment, the system will auto-create one. If only consignor email or ID is supplied, items map to the newest existing consignment — or a new consignment is auto-created using the consignor's default commission rule.
| Field Name | Required? | Description | Example Value |
|---|---|---|---|
| ConsignorID | Optional | Maps items to a consignment using the unique numeric ID for an existing consignor. | 9876 |
| ConsignorEmail | Optional | Maps items to a consignment using the email address of an existing consignor. | info@email.com |
| ConsignmentID | Optional | Maps items to a consignment using the unique ID number for an existing consignment record. | 12345 |
| ConsignmentReferenceNumber | Optional | Maps items to a consignment using its assigned reference number. | ABC-321 |
| CommissionRuleID | Optional | Assigns an existing commission rule to an auto-created consignment using the rule's unique ID number. | 21 |
| CommissionRuleReferenceNumber | Optional | Assigns an existing commission rule to an auto-created consignment using the rule's assigned custom reference number. | ABC-123 |
| Consignment Manager | Optional | The staff member managing the consignment. | Jane Smith |
| CatalogerName CatalogerEmail |
Optional | The name or email of the staff member who catalogd the item. Add separate columns for each. | John Smithj.smith@auction.com |
| Cataloged Photographed Approved |
Optional | Set to YES or NO to update inventory checklist statuses. Add separate columns for each. |
YES |
| InventoryStatus | Optional | Current workflow status. Must match an existing status name exactly. | Available |
| ShippingStatus | Optional | The current shipping status. Must match a system status exactly. | Not Shipped |
|
ItemLocationId
also:
Location |
Optional | The ID or name of the item's physical location in your warehouse. | Warehouse A |
| TotalSettlement | System | Auto-calculated on export. Do not include in upload files. | — auto — |
5 · Post-Sale & Winning Bidder Data
Used after an auction to finalise results. Upload via the Post Sale Data CSV type.
This section can be used as a template to upload sold data from any bidding platform — not just Bidsquare's own. If no user exists with the supplied email, the system will auto-create one with the name and email provided. Complete the bidder profile before invoicing to ensure sales tax calculations are correct.
| Field Name | Required? | Description | Example Value |
|---|---|---|---|
| ItemStatus | Optional | Set to Sold or Unsold. |
Sold |
|
SoldPrice
also:
Hammer Price |
Optional | The final winning bid amount. Used in Post Sale Data uploads. | 1800 |
|
BuyersPremium
also:
Buyer Premium |
Optional | The total buyer's premium for this item as a dollar value. If platform-specific BP is already configured and the correct platform is supplied, this field can be left blank — the system will auto-calculate BP based on your system rules. | 456 |
| BuyersPremiumOnline | Optional | Any additional buyer's premium for online platform bidders, as a dollar value. Can be omitted if platform-specific BP is configured and the correct platform is supplied. | 12 |
| Payment Status | Optional | The current payment status of the item. | Paid |
| Invoice Number | Optional | The invoice number associated with the sold item. | 123456 |
| Conditional | The winning bidder's email address. Required to map sales to an existing user, or to auto-create a user. If no user exists with the supplied email, the system auto-creates one with the name and email provided. Complete the bidder profile before invoicing to ensure accurate sales tax calculations. | bidder@email.com |
|
| BidderNumber | Conditional | The winning bidder's paddle number. Required if matching an existing bidder by paddle. | 042 |
| FirstName | Optional | The winning bidder's first name. | Jane |
| LastName | Optional | The winning bidder's last name. | Doe |
| Platform | Optional | The platform the winning bid came from. Must match an existing platform setting name exactly. | Invaluable |
| DateSold | Optional | The date the item was sold. Use ISO 8601 date format. | 2024-06-15 |
| PriceRealized | System | Auto-calculated on export (hammer price + buyer's premium). Do not include in upload files. | — auto — |
6 · Custom Data & Other Fields
For advanced users and those integrating with other platforms.
| Field Name | Required? | Description | Example Value |
|---|---|---|---|
| CustomFields | Optional | Update multiple custom fields at once in a single column. Format: FieldName1:Value1;FieldName2:Value2 |
Color:Blue;Era:Victorian |
| ExternalItemUrl | Optional | For Catalog Only sales — links to an external bidding page. | https://partner.com/lot/123 |
| TaxJarCategory | Optional | Product tax code for automated sales tax calculation via TaxJar. | 19005 |
| DisableTax | Optional | Set to 1 to disable sales tax calculations for this specific lot. |
1 |
| Note | Optional | Adds an internal note to the item. Not visible to bidders. | Check provenance before sale. |