Do not proceed until this is confirmed. See the Prerequisites section above.
Back to Documentation home
Bidsquare Platform · Data Migration & Setup
Bulk Upload Guide: Users & Consignors
Everything you need to migrate your bidder database and consignor records into Bidsquare via CSV — prerequisites, field references, linking profiles, and how to resolve common errors.
Prerequisites — Read Before You Upload Anything
Two things must be confirmed before running any bulk upload. Getting either wrong causes problems that are difficult to reverse.
Your White-Label website must be launched before uploading users
This is the single most important rule in this guide. Bidsquare manages two separate user environments: Bidsquare.com (the public marketplace) and your White-Label website (your own branded site). When you upload a user CSV, the system creates accounts on whichever site the admin is currently connected to.
If your White-Label site has not been launched and connected to your admin, the upload will create accounts on Bidsquare.com instead of on your site. Your customers will receive login credentials for a platform you didn’t intend, and the accounts will need to be recreated on your site after launch. This is not automatically correctable.
Confirm with your Bidsquare onboarding manager that your site is live and connected before running any user CSV upload. Soft launch (password-protected, not yet public) is sufficient — the site simply needs to exist and be connected to your admin panel.
Safe to upload — site is launched
Your White-Label site is live or in soft launch, and connected to your Bidsquare admin. Confirm this by visiting your site URL and checking it resolves to your branded auction site. If you see a Bidsquare-branded page, contact your onboarding manager before proceeding.
Green light
Do not upload — site not yet launched
Your White-Label site is not yet live or not yet connected to your admin. Uploading now will create user accounts on Bidsquare.com. Wait until your onboarding manager confirms the connection is active. This applies even if you have full admin access — admin access and site connection are independent.
Stop
Second Prerequisite — Required Setup Order
Commission rules must exist before consignors, and consignors before consignments
The Consignor upload requires a commission rule to be assigned to each consignor. The system will not create a consignor record without one. Before running any consignor CSV upload, ensure all your commission structures are configured in Consignments → Commission and Rules. If uploading both users and consignors as part of a migration, complete them in this sequence: 1) Commission rules → 2) Users CSV → 3) Consignors CSV → 4) Link profiles.
Using Demo for Test Runs
Your Demo environment (demo.bidsquare.com/seller) is a complete, independent copy of your admin with no real data. Use it to run a test upload with a small subset of your data before executing the full migration in Production.
Replace real emails with test addresses in Demo
When testing in Demo, replace real customer email addresses with dummy versions — e.g. yourname+test1@yourcompany.com. This prevents the system from accidentally sending signup emails to real customers during your test run. Gmail and most providers treat +tag addresses as valid while keeping them distinct from the real address.
Bulk User Upload
Migrating your bidder database — field reference, upload steps, and best practices.
Where to find this
Users › Bulk User List CSV Upload
User CSV Field Reference
Always download the latest template from the admin — do not build your own template from memory. Column headers are case-sensitive and must match exactly.
Billing and Shipping addresses are separate columns
The user CSV uses distinct Billing* and Shipping* column sets. Populate both wherever possible. Shipping address is used for sales tax calculations — a user without a valid shipping address will cause sales tax to be calculated incorrectly on their invoices. Use the Copy Shipping/Billing Address option at upload time to auto-populate the missing address set if you only have one.
| Field | Required? | Notes |
|---|---|---|
FirstName | Yes | Bidder’s first name. Appears on their account and all invoices. |
LastName | Yes | Bidder’s last name. |
Email | Yes | Must be unique. Duplicate emails are silently skipped — existing accounts are not overwritten. This is the primary identifier used for all subsequent matching (consignor linking, third-party imports, QuickBooks sync). |
Phone | Yes | Must be a valid format for the country. US: 10 digits, no spaces or country code (2315697894). International: include country code prefix. The most common upload failure — see the Errors section. |
Country | Optional | Two-character ISO country code: US, GB, CA, AU. Not the full country name. |
Currency | Optional | Three-character currency code: USD, GBP, CAD. |
Preferred | Optional | Set to 1 to mark as a Preferred Bidder. Leave blank on your first upload. Setting this on a bulk upload will immediately trigger the Add Preferred Bidder automated email to every marked user. Add preferred status in a separate, deliberate step after migration. |
CompanyName | Optional | Business or company name. Shown on their profile and invoices where relevant. |
CompanyUrl | Optional | Business website URL. |
LicenseNumber | Optional | Trade or dealer license number, where applicable. |
LicenseExpiryDate | Optional | Expiry date of the license. |
DisableTax | Optional | Set to 1 to disable sales tax calculations for this user (e.g. tax-exempt buyers). Leave blank for standard taxation. |
Billing* fields | Recommended | Separate columns for billing address: BillingFirstName, BillingLastName, BillingCompanyName, BillingAddress, BillingAddress2, BillingCity, BillingState, BillingZipCode, BillingCountry, BillingPhone. BillingCountry uses 2-character code. |
Shipping* fields | Recommended | Separate columns for shipping address: ShippingFirstName, ShippingLastName, ShippingCompanyName, ShippingAddress, ShippingAddress2, ShippingCity, ShippingState, ShippingZipCode, ShippingCountry, ShippingPhone. Used for sales tax calculations — populate wherever possible. ShippingCountry uses 2-character code. |
PrivateNotes | Optional | Internal staff notes. Not visible to the user. Supports a single-note format (plain text) or a multi-note format (date|note pairs, pipe-separated). Use the downloaded template as a formatting guide. |
Do not set Preferred Bidder status on your first bulk upload
Setting Preferred = 1 during a bulk upload will immediately trigger the Add Preferred Bidder automated email template to every user with that value. On a first migration upload, this sends a batch of unexpected emails to your entire customer base. Leave the Preferred column blank or remove it entirely on your initial upload. Set preferred status in a separate, deliberate pass after migration is complete.
Upload Options & Send Sign-Up Email
When you upload your CSV, the system displays a summary of your file with any errors or warnings before confirming. Several additional options are available at this point:
Force Update Existing Address
Existing user accounts with a matching email are auto-detected. Check this option to update their address information from the file. If unchecked, existing address fields are ignored and the original address information is preserved.
Optional
Copy Shipping / Billing Address
If only one address set (Billing or Shipping) is provided in your file, this option copies it across to the other set automatically. Recommended for most migrations to ensure both address sets are populated for sales tax purposes.
Recommended
Ignore Duplicates
Automatically selected if your file contains duplicate records or emails matching an existing account. Duplicate rows are skipped without failing the upload.
Auto-selected if needed
Send Sign-Up Email — this is NOT a CSV column
The Sign-Up Email option is a checkbox in the upload UI — not a field in your CSV file. It can be triggered in two ways: (1) check Send Sign-Up Email before confirming your upload, or (2) do it after the upload from the Users list by filtering to Pending Sign-Up Email Sent, selecting the relevant users, and using the Batch Action Send Sign-Up Email. This sends the Complete Registration email (subject: “Complete your account profile”) prompting users to set their password and complete their account. For bulk migrations, it is recommended to trigger this separately after upload rather than simultaneously — it gives you the opportunity to verify the upload before notifying customers.
User Account Email Flows
The system communicates with users automatically depending on how their account was created. Understanding these flows ensures your customers receive the right email at the right time.
1 — Direct sign-up on your website
When a user registers organically through your website.
Template: Welcome Email
Subject: Welcome To [Your Auction House]
Self-registration
Template: Welcome Email
Subject: Welcome To [Your Auction House]
2 — Single account created via admin
When you manually create a single user in the admin panel (Add User screen). A password is required at creation, so the system sends an email verification rather than a password-set prompt.
Template: Email Verification
Subject: Complete your registration
Admin-created
Template: Email Verification
Subject: Complete your registration
3 — After CSV bulk upload (Send Sign-Up Email)
Triggered when you use Send Sign-Up Email after a bulk upload. Users click the link to set their own password and complete their account. They then receive the standard Welcome Email as a second step.
Template: Complete Registration
Subject: Complete your account profile
Bulk migration flow
Template: Complete Registration
Subject: Complete your account profile
Upload Steps
1
Confirm your White-Label site is live and connected
2
Download the latest CSV template from the admin
Navigate to Users → Users Search → Add User dropdown → Bulk Userlist CSV Upload. Press Users CSV Sample to download the template with sample data. Never reuse a saved template — download fresh each time.
Users › Users Search › Add User › Bulk Userlist CSV Upload
3
Prepare and clean your data
- Deduplicate email addresses — each email can only exist once
- Standardise phone number formats per country
- Use 2-character country codes (
US,GB,CA) — not full country names - Populate both billing and shipping address fields wherever possible
- Leave the Preferred column blank on a first migration upload
- Replace real emails with test addresses if running in Demo first
4
Upload and review the file summary
Select your CSV and press Upload. The system displays a summary of your file with any Errors (red) — which must be resolved before the upload can proceed — and Warnings (yellow) — which are advisories that won’t prevent the upload. Hover over any row in the summary to see the specific issue.
5
Select upload options as needed
Enable Copy Shipping/Billing Address if your file only contains one address set. Enable Force Update Existing Address if you want to overwrite addresses on existing accounts. Do not check Send Sign-Up Email at this stage for large migrations — confirm the upload results first.
6
Confirm the upload, then send sign-up emails separately
Confirm the upload. Review the results — verify the “records created” count against your row count. Once satisfied, navigate to Users, filter by Pending Sign-Up Email Sent, select the relevant users, and use Batch Actions → Send Sign-Up Email to notify customers in a controlled, deliberate step.
User Upload Best Practices
1
Deduplicate your email list before you do anything else
Email is the system’s primary unique identifier. Duplicate emails are silently skipped — the upload report shows fewer records created than rows submitted. Run a deduplication pass before building your CSV. After deduplication, sort by Last Name to spot near-duplicates that share an address but have slightly different email addresses.
2
Never send signup emails during a bulk migration
Sending signup emails to hundreds or thousands of customers simultaneously during a migration is the most disruptive thing you can do. Customers receive an unexpected email about an account they didn’t sign up for, often without context. Plan a separate, intentional onboarding email campaign instead — one that explains the new platform, provides a login link, and offers support.
3
Standardise phone numbers before uploading — by country
US numbers: 10 digits without country code —
2125551234 — or with +1 prefix. UK: include area code with or without +44. International: use +[country code][number]. Remove all brackets, dashes, and spaces. A mix of formats will cause a subset of records to fail silently.4
Upload international customers in separate batches by country
If your database includes customers from multiple countries, consider batching by country. This makes it much easier to spot country-specific format errors in the upload report and allows you to apply country-specific data cleaning rules to each batch independently.
5
Keep a record of what was uploaded and when
Save a copy of every CSV you upload, with the date and the upload result count. Without this audit trail, diagnosing problems from support calls becomes guesswork months after the migration.
Consignor Upload
Creating consignor profiles in bulk — how it differs from user upload, field reference, and key considerations.
Consignor upload is separate from user upload — these are different record types
User records and Consignor records are independent profiles. A user account is a bidder login. A consignor profile is a seller record used for consignments, commissions, and settlements. The same person can have both — and often does — but they must be created separately and then linked after creation. Creating a user account does not automatically create a consignor profile, and vice versa.
Where to find this
Consignments › Consignors › Import
Commission rules must exist before consignors can be created
The commission rule field is required on every consignor record. Ensure all your commission structures are configured in Consignments → Commission and Rules before importing. The name you enter in your consignor CSV must match exactly, including capitalisation.
Consignor CSV Field Reference
Always download the latest template from the admin. Column headers are case-sensitive. The consignor CSV uses Billing* address fields (not shipping).
Billing address is critical for settlements
Consignor records use billing address fields. A consignor without a complete billing address may result in incomplete or undeliverable settlement documents. Populate all Billing* fields wherever possible, especially for consignors who receive regular payouts by cheque or wire transfer.
| Field | Required? | Notes |
|---|---|---|
FirstName | Yes | Consignor’s first name. |
LastName | Yes | Consignor’s last name or company/estate name. |
Email | Yes | Must be unique in the consignors table. This is the consignor’s primary identifier — use the same email address they use as a bidder (if applicable) to make linking straightforward. |
UserEmail | Optional | Used to link this consignor profile to an existing user (bidder) account in bulk via CSV. Enter the email address of the user account you want to link. If a matching user exists, the link is created automatically on import — no manual linking step required. Leave blank if no user account exists or linking is not needed. |
Phone | Yes | Same format requirements as user upload. Most common source of failures. |
CompanyName | Optional | Business or trading name, if applicable. |
Country | Optional | Two-character ISO country code: US, GB, CA, AU. |
Status | Optional | Accepts active or inactive. Defaults to active if omitted. |
DefaultCommissionRuleId | One required | The system-generated numeric ID of the commission rule to assign. Use this or DefaultCommissionRuleReferenceNumber — one of the two is required. Find the ID by opening the rule in Consignments → Commission and Rules. |
DefaultCommissionRuleReferenceNumber | One required | The custom reference number assigned to an existing commission rule. Use this or DefaultCommissionRuleId. The value must match exactly, including capitalisation. |
ReferenceNumber | Optional | Your internal consignor ID from a previous system. Enables cross-referencing with legacy records indefinitely after migration. |
Billing* fields | Recommended | Billing address columns: BillingFirstName, BillingLastName, BillingCompanyName, BillingAddress, BillingAddress2, BillingCity, BillingState, BillingZipCode, BillingCountry, BillingPhone. Used for settlement documents and cheques. BillingCountry uses 2-character code. The name on settlement documents and cheques is drawn from BillingFirstName / BillingLastName / BillingCompanyName — set these carefully for estates, businesses, or proxy sellers where the payee differs from the consignor’s name. |
Link consignor and user profiles in bulk using the UserEmail column
The UserEmail column is the bulk equivalent of the Link Existing User function. If you populate it with the email address of an existing user account, the consignor profile is automatically linked to that user on import — no manual linking required. This means for any consignor who is also a bidder, you can complete the user upload first, then include their UserEmail in the consignor CSV to link both profiles in a single operation. After importing, you can then enable Consignor Login for the relevant profiles.
Consignor Upload Best Practices
1
Use the same email in both records — and populate UserEmail in the consignor CSV to link in bulk
If a consignor also bids at your auctions, use the same email address in both their user record and their consignor record. Then populate the
UserEmail column in your consignor CSV with that email — the system will automatically link both profiles on import. This is the recommended approach for bulk migrations: upload users first, then upload consignors with UserEmail populated, and linking is handled entirely within the CSV with no manual step required per profile.2
Map every consignor to their correct commission rule before importing
The Commission Rule field is required, but it’s equally important that it’s correct. A consignor imported with the wrong commission rule will generate incorrect settlement calculations on every consignment until someone notices. Build a lookup table in your spreadsheet mapping each consignor to their rate, then cross-reference against your rule names in Bidsquare before uploading.
3
Populate the Reference Number field for every consignor from a previous system
Enter each consignor’s legacy ID as the Reference Number. Long after migration, staff will receive calls from consignors quoting their “old number.” Without this field, tracing that caller requires a name search — which fails if the name was entered differently. With Reference Number populated, a single search finds the record instantly.
4
Set the Billing name fields carefully — they appear on settlement documents and cheques
The
BillingFirstName, BillingLastName, and BillingCompanyName fields are drawn from to produce the payee name on settlement statements and printed cheques. For individuals this is usually their own name. For estate consignments it should be the estate attorney, executor, or trust entity. For business consignors it should be the trading name, not the contact person's name. Review every billing name entry before submitting the CSV — correcting it after the fact requires editing each profile individually.5
Migrate historical notes with a date stamp
If your previous system contains relationship notes, special handling flags, or rate history, import them into the Notes field. Prefix each note with the original date:
[2023-04-15] Negotiated to 15% flat for high-volume lots. Approved by [Name]. Without the date stamp, imported notes look like current information and staff can’t tell how old the context is.Linking User & Consignor Profiles
Why linking matters, how to do it, and what the Consignor Login Portal enables for linked accounts.
Why linking matters — the Consignor Login Portal & unified records
When a consignor profile is linked to a user account and Consignor Login is enabled, the consignor gains access to a self-service portal within their My Account area on your website. They can view their own consignment data, track lot results, and download settlements — without requiring any staff involvement. This is one of the most valuable relationship management features in the system and one of the most commonly overlooked.
What the Consignor Portal Shows
My Consignments
All their active and historical consignment contracts — consignment name, reference number, status, and which auction each consignment is associated with.
Self-service
Selling Items
All their items across all consignments — title, lot number (once assigned), estimate, starting bid, and current auction. Items appear as soon as they are added to a consignment, regardless of whether the auction is published.
Live immediately on adding
Settlements
All their settlement statements — once sent by your team. They can view the line-item breakdown of hammer prices, commission, charges, and net payout, and download a PDF copy. New settlements (not yet sent) are not visible.
Sent settlements only
Items appear in the portal immediately — before cataloging is complete
As soon as an item is added to a consignment, it appears in the consignor’s Selling Items tab if their portal is enabled. A consignor could see a placeholder record with only a title and no images or description. Enable Consignor Login selectively and only after items have been fully catalogd — or communicate clearly to consignors what they will see at each stage.
How to Link a Consignor and User Profile
1
Open the consignor profile
Consignments › Consignors › [consignor name] › Edit
2
Use Link Existing User to find the matching account
In the Edit view, locate the Link Existing User field. Type the consignor’s name or email. If a user account exists with that email, it appears in the dropdown — select it. If the user account doesn’t exist yet, create it first, then return to this step.
3
Enable Consignor Login
After linking, locate the Enable Consignor Login toggle and set it to On. This activates the portal for this specific consignor. It is Off by default — enabling it is a deliberate per-consignor decision.
4
Verify using Impersonation
Navigate to the linked user’s profile in Users and click Impersonate. You should see My Consignments, Selling Items, and Settlements tabs in their My Account area. If these don’t appear, check that Enable Consignor Login is On and the correct user is linked.
Users › [user profile] › Impersonate
Linking at Scale — Migration Strategy
Bulk linking via the UserEmail CSV column
The fastest way to link profiles at scale is to populate the
Done at import via CSV
UserEmail column in your consignor CSV before importing. If a user account exists with the matching email, the link is created automatically — no manual step required per profile. For any consignor who is also a bidder, upload the user CSV first, then include their email in UserEmail on the consignor CSV.Linking and enabling the portal are two separate steps
Linking (via
Link via CSV · Enable manually
UserEmail in the CSV or Link Existing User in the UI) creates the connection between the two records. Enabling Consignor Login is a separate, deliberate action you take per consignor once their items are catalogd and you’re ready for them to have portal access. The two steps are independent — link all profiles during migration, enable the portal selectively when the time is right.New consignors: always check Link Existing User before creating the profile
When creating new consignor profiles going forward, always search Link Existing User first. If the person already has a bidder account, selecting them from the dropdown auto-fills their name, email, phone, and address — and creates the link from the moment of creation rather than requiring a separate linking step later.
Common Errors & How to Resolve Them
The most frequent upload failures — what causes them, how they present, and exactly what to fix.
User Upload Errors
| Error | Behavior | Cause & Resolution |
|---|---|---|
| Invalid phone number | Row skipped | The phone number format doesn’t match the expected format for the country. Fix: US: 10 digits, no spaces, no country code (2315697894). International: use the full number including country code prefix. Remove all brackets, dashes, and spaces from every number in the column before uploading. |
| Duplicate email — row skipped silently | Silent skip | An account with this email already exists. The row is skipped without an error message — the upload report shows fewer records created than rows submitted. Fix: Deduplicate your email column before uploading. Use Force Update Existing Address if you need to update an existing account’s address. |
| Invalid postal code format | Row skipped | The postal code format doesn’t match the country code in the same row. Fix: Verify postal codes match their country: US: 5-digit or ZIP+4; UK: standard postcode format; Canada: A1A 1A1 format. |
| Country code not recognized | Row skipped | The Country field requires a 2-character ISO code — US, GB, CA, AU. Full country names (United States, United Kingdom) are not accepted. Fix: Convert all Country values to 2-character ISO codes before uploading. |
| Accounts created on Bidsquare.com instead of your site | Wrong platform | Your White-Label site was not live and connected to your admin at the time of upload. Fix: Contact your Bidsquare onboarding manager immediately. Accounts will need to be recreated on your site after the connection is established. There is no automated way to move accounts between platforms retroactively. |
| Fewer records created than rows submitted | Silent skip | Some rows were silently skipped due to validation failures or duplicate emails. The upload completes without an overall error. Fix: Compare “records created” count against total rows. Re-upload just the missing rows to isolate the specific format issue. |
| Preferred Bidder email triggered unexpectedly | Automated email fired | The Preferred column was set to 1 for some users, which immediately triggered the Add Preferred Bidder email to those users. Fix: Leave the Preferred column blank on all migration uploads. Set preferred status in a separate, deliberate batch action after migration is verified complete. |
Consignor Upload Errors
| Error | Behavior | Cause & Resolution |
|---|---|---|
| Commission rule not found | Row fails | The value in DefaultCommissionRuleId or DefaultCommissionRuleReferenceNumber doesn’t match any existing rule. Fix: Open Consignments → Commission and Rules to verify the ID or reference number. If using the reference number, the match is case-sensitive — copy it directly from the admin rather than retyping. |
| Duplicate email — consignor not created | Row skipped | A consignor profile already exists with this email. Fix: The existing record is not overwritten. Remove duplicate-email rows from your import file. Update existing consignor details by editing individual profiles. |
| UserEmail doesn’t match any user account | Link not created | The email address in the UserEmail column doesn’t match any existing user account. The consignor record is still created, but no link is established. Fix: Verify the user account exists in Users and that the email addresses match exactly. Either create the user account first and re-import, or link the profiles manually after import via the consignor’s Edit screen. |
| Payee name appears incorrectly on settlements | Check results | Settlement documents draw the payee name from BillingFirstName, BillingLastName, and BillingCompanyName. If these were left blank or set to the wrong name (e.g. the contact person’s name instead of the estate or business name), settlements will show the wrong payee. Fix: Edit the consignor profile directly and update the Billing name fields. |
| Commission rule applies wrong structure | Check results | The correct rule was matched but it maps to the wrong structure (e.g. a flat-rate consignor assigned a step-down rule). No upload error is shown — but settlement calculations will be wrong. Fix: Spot-check 10–15 consignor records after import and verify the assigned commission rule displays the correct rates. Edit mismatches directly on the profile. |
Linking Errors
| Issue | Behavior | Cause & Resolution |
|---|---|---|
| UserEmail column produces no link (CSV import) or Link Existing User returns no results (manual) | Link not created | No user account exists with that email, or the email in UserEmail (CSV) / the search field (manual) differs from the user record by even a single character. Fix: Confirm the user account exists in Users and that the email addresses match exactly — check for trailing spaces, different capitalisation, or the use of a different email address (e.g. personal vs. business). Either create the user account first and re-import the consignor CSV, or use the Link Existing User field in the consignor Edit screen to link manually. |
| Portal tabs don’t appear after linking | Check settings | The profiles are linked but Enable Consignor Login has not been toggled On. Linking and enabling the portal are two separate steps. Fix: Consignments → Consignors → [consignor] → Edit → Enable Consignor Login → On → Save. Verify by impersonating the linked user. |
| Consignor can see incomplete items | Disable portal | Consignor Login was enabled before cataloging was complete. Items appear in the Selling Items tab as soon as they’re added to the consignment. Fix: Toggle Enable Consignor Login to Off until cataloging is complete for all items in the consignment. Re-enable once the catalog is ready. |
General Best Practices
1
Always test in Demo before Production — every time, not just the first time
Even after several successful uploads, always test a new batch in Demo first. Data quality varies between sources — a new export from your CRM may have different formatting than the last one. The cost of a failed Production upload is hours of cleanup. The cost of a Demo test run is five minutes.
2
Never modify column headers — use the sample CSV as your template
Column headers are case-sensitive and must match the template exactly. Even a trailing space in a header name causes that column to be ignored. Use the Users CSV Sample button in the upload screen to download the official sample — it contains the exact headers and example data. For consignors, download the template from the import screen. Never build your own template from memory or reuse a saved copy from a previous session.
3
Compare “records created” against “rows submitted” after every upload
If the “records created” count is lower than your row count, rows were silently skipped. Don’t assume this is just duplicates — investigate. Calculate the difference and determine whether skipped rows represent real data loss (bad phone formats, unrecognized country names) or expected deduplication (genuinely duplicate emails).
4
Plan your consignor portal outreach separately from the upload itself
Creating consignor profiles and enabling Consignor Login does not notify consignors. Your consignors will only know the portal exists if you tell them. Plan this as a separate communication after migration is complete — include instructions on what they can see, a direct login link, and a support contact for questions.