Import Wizard Overview
PrimeConnect's import wizard is a guided, multi-step process that takes you from a raw spreadsheet file to fully imported QuickBooks records. The wizard is designed to catch errors before they reach QuickBooks, saving you time and preventing data quality issues.
The import wizard consists of six steps:
- Choose Entity Type — select what kind of QuickBooks record you are importing (e.g., Invoices, Customers, Journal Entries).
- Upload Your File — drag and drop or browse to select your Excel or CSV file.
- Map Fields — match your spreadsheet columns to QuickBooks fields, with automatic fuzzy matching.
- Handle Missing References — resolve any customers, items, accounts, or other references that do not yet exist in QuickBooks.
- Validate Data — PrimeConnect checks every row for errors, invalid formats, and missing required fields.
- Preview & Import — review your data one final time and execute the import.
You can navigate back and forth between steps without losing your work. The wizard preserves your mapping selections, file data, and validation state throughout the session.
Supported File Formats
PrimeConnect accepts the following file formats for import:
| Format | Extension | Notes |
|---|---|---|
| Excel (modern) | .xlsx | Recommended. The modern Excel format preserves data types (dates, numbers) most reliably. |
| Excel (legacy) | .xls | Supported for compatibility with older files. Consider saving as .xlsx for best results. |
| CSV | .csv | Comma-separated values. UTF-8 encoding recommended. All values are treated as text and parsed by PrimeConnect. |
Need to convert your file format? Try our free accounting tools to transform files between formats. For example, you can convert CSV files to IIF format for QuickBooks Desktop import, or convert Excel files to QBO if your workflow requires it.
For detailed guidance on preparing your files, including column naming conventions, date formatting, and encoding, see the Sample Import Files & Templates article.
Step 1: Choose Entity Type
The first step is to tell PrimeConnect what kind of QuickBooks record you want to import. Entity types are organized into two categories:
Lists (master records)
Lists are the foundational records in QuickBooks — the things that transactions reference. These include:
- Accounts — Chart of Accounts entries (Bank, Income, Expense, etc.)
- Items — Products and services (Service, Inventory Part, Non-Inventory Part, etc.)
- Customers — Customer and job records
- Vendors — Vendor/supplier records
- Employees — Employee records
- Classes — Class tracking categories
- And more — Sales Reps, Payment Methods, Ship Methods, Terms, Price Levels, etc.
Transactions
Transactions are the day-to-day financial records that reference list items. These include:
- Invoices — Sales invoices with line items
- Bills — Vendor bills/payables
- Journal Entries — General journal debits and credits
- Sales Receipts — Point-of-sale transactions
- Credit Memos — Customer credit memos
- Estimates — Quotes and proposals
- Purchase Orders — Vendor purchase orders
- And many more — Checks, Deposits, Transfers, Receive Payments, Sales Orders, Credit Card Charges, etc.
For a complete list of all 40+ supported entity types and which operations each supports, see Supported QuickBooks Entity Types.
Step 2: Upload Your File
Once you have selected an entity type, the next step is to provide your data file.
Uploading
You can provide your file in two ways:
- Drag and drop — drag your Excel or CSV file directly onto the upload area in PrimeConnect.
- Browse — click the upload area to open a file picker dialog and navigate to your file.
What happens after upload
PrimeConnect immediately parses your file and performs several checks:
- File format validation — confirms the file is a valid Excel or CSV file.
- Header detection — reads the first row of your spreadsheet as column headers. These headers are used for automatic field matching in the next step.
- Row count — counts the total number of data rows (excluding the header) and displays the count so you can verify the file was read correctly.
- Data preview — shows a preview of the first several rows so you can confirm the data looks correct.
Step 3: Map Fields
Field mapping is where you tell PrimeConnect which column in your spreadsheet corresponds to which field in QuickBooks. This is a critical step — correct mapping ensures your data ends up in the right places.
Automatic matching
PrimeConnect uses fuzzy matching to automatically map your column headers to QuickBooks field names. For example:
- "Invoice Number" or "Inv #" maps to RefNumber
- "Customer Name" or "Customer" maps to CustomerRef
- "Amount" or "Total" maps to the appropriate amount field
- "Date" or "Invoice Date" maps to TxnDate
Auto-matched columns are shown with a green checkmark. Columns that could not be auto-matched will have an empty dropdown, allowing you to select the correct field manually.
Manual mapping
For columns that were not automatically matched, click the dropdown next to the column header and select the appropriate QuickBooks field from the list. The dropdown includes a search/filter input at the top so you can quickly find the field you need.
Required fields
Required fields are marked with an asterisk (*). The import cannot proceed until all required fields are mapped. Which fields are required depends on the entity type — for example, Invoices require CustomerRef and at least one line item, while Customers only require a Name.
Saving and loading templates
If you import the same type of file regularly, you can save your mapping configuration as a template and load it later to skip the manual mapping step entirely. For detailed instructions, see the Field Mapping & Saved Templates article.
Mapping rules
Every QuickBooks field row on the Map Fields page has a Rules column with an Add rule button. Rules let you clean up or fill in values without editing your file — for example, use a default if a cell is blank, set a constant value, find and replace text, trim spaces, change to upper or lower case, add text from another column, take part of the text, or skip a row when a condition matches. Rules are saved together with the mapping. For a full walkthrough, see Mapping Rules.
Step 4: Handle Missing References
When your import data references other QuickBooks records — customers, items, accounts, vendors, etc. — PrimeConnect checks whether those records already exist in QuickBooks. Any references that cannot be found are flagged as "missing references."
For example, if you are importing invoices and one row references a customer named "Acme Corp" but no customer with that name exists in your QuickBooks file, it will appear as a missing reference.
Resolution options
You have two options for handling missing references:
- Auto-create — PrimeConnect can automatically create the missing records in QuickBooks during the import. This is the fastest option and is controlled by toggles in Settings.
- Manual resolution — Go into QuickBooks, create the missing records yourself with the exact data you want, then return to PrimeConnect and re-validate.
Missing references are organized into tabs by type (Items, Accounts, Entities, etc.). Each tab shows the missing values along with their current resolution status. For a deep dive into this step, see Handling Missing References During Import.
Step 5: Validate Data
Before any data is sent to QuickBooks, PrimeConnect performs a thorough validation of every row in your file. This step catches errors that would otherwise cause import failures, saving you time and preventing partial imports.
What gets validated
- Required fields — every required field must have a value in every row.
- Date formats — dates must be in a recognized format (MM/DD/YYYY, YYYY-MM-DD, etc.).
- Numeric values — amounts, quantities, and rates must be valid numbers.
- Reference existence — all referenced items, customers, accounts, etc. must exist in QuickBooks (or be set to auto-create).
- Duplicate detection — when update mode is disabled, PrimeConnect flags records that already exist in QuickBooks to prevent accidental duplicates.
- Field length limits — some QuickBooks fields have maximum character lengths that PrimeConnect checks against.
Validation results
After validation, each row receives a status indicator:
- Green check — the row is valid and ready to import.
- Red X — the row has one or more errors. Click the row to see the specific error message.
- Yellow warning — the row has a non-critical issue that may need attention (e.g., a value will be truncated to fit the field length limit).
For detailed information on fixing validation errors and re-validating, see Data Validation & Preview.
Step 6: Preview & Import
This is the final step before your data is sent to QuickBooks. The preview screen shows your data in a table format exactly as it will be imported, giving you one last chance to review everything.
Reviewing your data
The preview table displays all rows with their mapped field values. Scroll through the table to verify that the data looks correct. Pay special attention to:
- Date values — are they in the correct format and expected range?
- Amounts — do the numbers look right? Are there any unexpected zeros or very large values?
- References — are customer names, item names, and account names spelled correctly?
Executing the import
When you are satisfied with the preview, click the Import button to begin. Before the first record is sent, a small dialog titled Choose import number and date formats asks how amounts and dates in this file should be read. The same dialog includes the Group rows into transactions across the whole file checkbox (see Multi-Line Transactions below). Click Continue import, and PrimeConnect sends each record to QuickBooks one at a time and displays a progress indicator showing:
- The current record number out of the total (e.g., "Processing 23 of 150")
- A progress bar showing overall completion
- Running counts of successful, updated, and errored records
Multi-Line Transactions
Transactions such as invoices, bills, and journal entries usually have more than one line. In your spreadsheet, each line is its own row, and every row repeats the columns that identify the transaction it belongs to (for an invoice: the customer and the reference number). PrimeConnect groups those rows into one QuickBooks transaction before sending it.
How rows are grouped
By default, rows that belong to one transaction may appear anywhere in the file — they do not need to be next to each other. PrimeConnect matches rows by the transaction's identity columns, so three rows for invoice 1001 on lines 3, 7, and 42 become a single three-line invoice. The first row of the transaction supplies the header values; later rows add lines. Within a transaction, lines keep the order they have in your file.
The identity columns depend on the entity type:
| Entity types | Rows belong to the same transaction when these match |
|---|---|
| Invoice, Credit Memo, Estimate, Sales Order, Sales Receipt, Receive Payment | Customer + Reference number (RefNumber) |
| Bill, Item Receipt, Vendor Credit | Vendor + Reference number (RefNumber) |
| Purchase Order, Credit Card Charge, Credit Card Credit, Transfer Inventory | Reference number (RefNumber) |
| Journal Entry | My Reference No. (MyRefNumber) |
| Check, Deposit, Bill Payment (Check) | My Transaction No (MyTxnNo) |
| Bill Payment (Credit Card) | Payee + Payment method |
| Vendors, inventory and non-inventory items, service and other-charge items, discount/payment/subtotal items, Group Items, Inventory Assemblies, Units of Measure, per-item Price Levels, and Sales Tax Groups | Name |
A row whose identity is incomplete — for example an invoice row with a blank reference number — is never merged with any other row. It fails validation on its own with the usual message, which names the column from your file: "[Column] is blank. Please specify its value.". Whole-file grouping applies to the standard entity types listed above; other types, and custom imports, group adjacent rows only.
Header fields must agree
Some columns describe the whole transaction rather than a single line: transaction date, due date, ship date, reference number, customer/vendor/payee, currency, exchange rate, AR/AP account, terms, UniqueKey, bank or deposit account, payment method, template, sales rep, PO number, FOB, and customer message. Put these values on the first row of each transaction; later rows of the same transaction may leave them blank, or repeat the same value.
If two rows of the same transaction contain different non-blank values for one of these columns, the whole transaction fails validation. Every row of that transaction shows a message that names the two rows and the column from your file, for example:
Transaction rows disagree: Rows 3 and 7 disagree on Invoice Date: '2026-01-05' vs '2026-01-06'
Nothing from that transaction is sent to QuickBooks. Other transactions in the file still import normally. Fix the value in your file so the rows agree (or blank out the extra copies) and re-import.
Duplicate list names and price levels
Repeated vendor or item names share one record when their mapped values agree. Different non-blank values, such as two phone numbers for the same vendor, produce Transaction rows disagree on every row of that record, and nothing from that record is sent to QuickBooks. Identical duplicates merge harmlessly.
Group Items and Inventory Assemblies may have different item names and quantities on their lines. Units of Measure may have different related unit names, abbreviations, and conversions; per-item Price Levels may have different item references, prices, and adjustments; Sales Tax Groups may have different tax items. Other mapped values must agree. Fixed-percentage Price Level rows always remain separate records, even when their names match.
A grouping conflict is added alongside any earlier validation error, so datatype messages remain visible. Stopping an import also preserves validation errors on rows that have not been submitted.
On Retry, rows already marked Imported or Updated keep those results, together with their transaction lines, even if you stop the retry before it starts or partway through. They remain in the earlier import's history; the retry's totals and record details exclude them. Its notes show how many rows completed in an earlier run were skipped.
Switching to adjacent-row grouping
On the Import step, the Group rows into transactions across the whole file checkbox controls this behavior. It is checked by default and is offered in the Choose import number and date formats dialog that appears before the import starts, and again on the results page for any re-import from that page. Both controls use the same per-import choice; changing it in the dialog updates the checkbox on the results page.
Uncheck it to use the older behavior: PrimeConnect compares each row only with the row immediately before it, so the lines of one transaction must be adjacent. With the box unchecked, rows for the same invoice that appear later in the file start a second invoice (or an update, if Update Existing Records is enabled).
Understanding Results
After the import completes, PrimeConnect displays a results summary showing the outcome for every row.
Result statuses
| Status | Color | Meaning |
|---|---|---|
| Imported | Green | The record was successfully created in QuickBooks. This is a new record that did not previously exist. |
| Updated | Blue | The record already existed in QuickBooks and was updated with the new data (only when "Update Existing Records" is enabled in Settings). |
| Error | Red | The record could not be imported. Click the row to see the specific error message from QuickBooks. |
| Skipped | Gray | The record was intentionally skipped — either because it is a duplicate and update mode is off, or because a validation error was not resolved. Rows skipped by a mapping rule show "Skipped by mapping rule: …" instead; they are never sent to QuickBooks and do not count as imported or failed. |
| Not submitted | Amber | You stopped the import before this row was sent. The row shows "Cancelled before submission to QuickBooks." and the summary reads "Import stopped safely — N imported, M not submitted." Only rows that were never sent get this status; rows already sent keep their real result (Imported, Updated, or Error), even when their lines were scattered across the file. Re-import only the not-submitted rows. |
Overall summary
The results screen shows a summary bar with the total counts for each status. A fully successful import shows all records in green. A partial success shows a mix of green and red/yellow. The summary also includes the total elapsed time for the import operation.
Error details
Each errored row includes the specific error message returned by QuickBooks. Common error messages include:
"Object not found"— a referenced item, customer, or account does not exist in QuickBooks."Invalid date"— the date value could not be parsed."Duplicate name"— a record with this name already exists (for list items like Customers or Vendors)."This feature is not enabled"— the QuickBooks edition or company file settings do not support this record type.
Every import operation is saved to your operation history so you can review it later or roll it back if needed.
Interrupted QuickBooks Requests
If a reference-creation request is interrupted, PrimeConnect stops sending records. Unsent eligible rows show Not attemptedand count as errors. When QuickBooks confirms the request was not processed, Activity History records a batch with errors and saves the stop reason in its notes. If the reference outcome is uncertain, the batch remains Recovery Required. A transport stop does not count as a user cancellation or Stopped Safely.
Sometimes a request reaches QuickBooks but the reply never makes it back — for example, QuickBooks closes, a dialog pops up, or the connection drops mid-import. PrimeConnect never resends a request on its own in this situation, because doing so could create duplicates. Instead, the affected rows show one of these messages:
- "QuickBooks outcome unknown. Verify this record in QuickBooks before retrying." — The request was sent, but PrimeConnect could not confirm the result. Open QuickBooks and check whether the record exists. Then open the History window (Activity History), filter by status Recovery Required, open the import, and use Retry automatic recovery or Resolve selected item to record what you found.
- "QuickBooks did not process this batch (it was unavailable). Nothing was changed; retry the import." — QuickBooks confirmed it never received the request (a modal dialog was open, QuickBooks was busy, or it could not start). Nothing was written, so it is safe to retry.
- "Not attempted: an earlier QuickBooks request was interrupted. Resolve it, then retry." — This row was never sent because an earlier request in the same import was interrupted. Resolve the earlier item first, then re-import only the rows that were not attempted.
Auto-created references (customers, items, accounts, and so on) follow the same rules. Until every Recovery Required item is resolved, PrimeConnect will not start a delete or rollback — the message you see points you back to Activity History.
Tips for Successful Imports
Follow these best practices to ensure smooth, error-free imports:
- Start with a small test batch. Before importing your full dataset, try importing just 5-10 rows first. This lets you verify that your field mapping is correct and there are no unexpected issues. You can always roll back a test import.
- Use the sample files as templates. PrimeConnect includes sample Excel files for every entity type. Download these from the Sample Import Files article and use them as a starting point for your own data.
- Enable auto-create for references. If your import references customers, items, or accounts that may not exist yet, enable auto-create in Settings. This prevents missing-reference errors and streamlines the import process.
- Save your mapping templates. If you import the same type of file regularly (e.g., monthly invoices from an external system), save your field mapping as a template. Next time, load the template and skip the mapping step entirely.
- Name your columns descriptively. Use column headers that closely match QuickBooks field names. This improves auto-matching accuracy and reduces manual mapping effort.
- Use .xlsx format over CSV. Excel files preserve data types (dates, numbers) more reliably than CSV. With CSV, all values are text and must be parsed, which can lead to ambiguities (e.g., "01/02/2025" could be January 2 or February 1 depending on locale).
- Import lists before transactions. If you need to import both customers and invoices, import the customers first. This ensures they exist in QuickBooks when the invoices reference them.
- Review results carefully. After every import, check the results screen for errors. Fix the errored rows in your source file and re-import only those rows.
