Back to Help Center
ClientSynq
QuickBooks tools

Import invoices into QuickBooks

Enterprise plan

Last updated: October 8, 2026

The QuickBooks import tool creates new invoices in your QuickBooks company from a CSV file. You map your columns to QuickBooks fields, fix anything the check finds, and then confirm. It imports invoices only.

Before you start

  • You need the Enterprise plan.
  • Your role needs the Import to QuickBooks permission (Roles page, QuickBooks Tools group). Owners have every permission.
  • QuickBooks must be connected.
  • Every customer and every product or service in your file must already exist in QuickBooks. The import does not create them. See Set up products and services in QuickBooks.
  • Prepare your file:
    • It must be a .csv file of up to 10MB, with at most 1,000 rows.
    • The first row must contain column headers.
    • Each row is one invoice line. Rows that share an Invoice Number become one invoice.
    • The page asks for dates as MM-DD-YYYY, for example 01-15-2025. Dates written YYYY-MM-DD, for example 2025-01-15, also work.

Excel files (.xlsx, .xls) are rejected. In Excel, choose Save As → CSV (Comma delimited) and upload the .csv file.

Steps

1. Upload your file

  1. In the sidebar, click QuickBooks Online Import. The QuickBooks Import Tool page opens on the Invoices tab. The other tabs are not available.
  2. Drop your file on the upload area, or click Choose File.

Screenshot to come: QuickBooks Import Tool → Invoices tab with the upload area and Required Information box
public/help/tools/qbo-import-1.png

2. Map your fields

The Map Your Fields page lists each QuickBooks field in three groups: Required Fields, Header Fields and Line Item Fields. Required fields have a red asterisk (*).

  1. If a saved template matches your file, a box at the top says Perfect Match Found! or Similar Template Found. Click Use This Template to apply its mapping, or Start Fresh to ignore it. Click Show N other templates to pick a different one. Below it, your organization's saved templates are listed with how often each was used. Click a template to apply its mapping. With no saved templates, the list says No templates yet.
  2. For each field you want to fill, choose the matching column under Your CSV Column. ClientSynq preselects columns whose names match a field name. Check them.
  3. For Email Status, if your file has no column for it, you can pick a value for every invoice under -- Or set default --: Send now (NeedToSend) or Don't send email (NotSet).
  4. Watch the counter at the top: Required must show every required field mapped.
  5. Click Continue to Validation.

Hover over a field name to see what it expects and an example. The field reference below lists every field.

Screenshot to come: QuickBooks Import Tool → Map Your Fields with the class tracking line and field list
public/help/tools/qbo-import-2.png

3. Fix validation errors

ClientSynq checks every row against QuickBooks. You see Total Rows, Valid Rows and Errors, and a Data Preview of your mapped columns. Rows with errors are shaded red.

If the page says Ready to Import, go to step 4. If it says Cannot Proceed, fix the errors in one of two ways:

  • Edit in place. Cells with an error are editable. Hover over a red cell to read the error, type the correct value, click Save Changes, then click Re-validate. Tick Only show rows with errors to narrow the list.
  • Fix the file. Click Export Issues to download a CSV of every issue with its row, field and message. Correct your file and save it as CSV. Click Back to Mapping, then Back to Upload, and upload the corrected file. Your mappings are kept (the page shows Field Mappings Preserved), so you go straight back to validation. To map again from scratch, click Clear mappings and start fresh.

Screenshot to come: QuickBooks Import Tool → validation results with Data Preview and an error cell
public/help/tools/qbo-import-3.png

4. Import

  1. Click Proceed to Import.
  2. A summary opens: Create N invoices in QuickBooks Online. It shows the rows in your file, the invoices to create, how many have a client email address and how many are flagged "Needs to send".
  3. Click Create N invoices. Above 50 invoices you must also type the count and tick a statement first. See Confirm a large change.
  4. Keep the window open while Importing to QuickBooks... runs. Invoices are created in small batches.

What happens next

The results page shows one of:

  • Import Complete! Every row was imported.
  • Import Partially Complete. Some rows failed. Each invoice is created on its own, so one rejected invoice does not stop the others.
  • Import Failed. No rows were imported.

Click Download Report for a CSV with the import summary and every row of your file, each marked OK or FAILED with the error. Click Start New Import to begin again.

If you did not use a template, the Save Field Mapping Template dialog opens after a completed import. Enter a Template Name and an optional Description, tick Set as default template if you like, and click Save Template. Templates are saved for your organization and suggested when a later file has matching column headers.

ClientSynq does not email your clients during an import. An invoice with Email Status NeedToSend is flagged "Needs to send" in QuickBooks and is emailed only when you send it from QuickBooks.

Recent Imports

The Recent Imports table at the bottom of the page lists your organization's imports with File Name, Type, Status, Progress (rows processed and failed) and Date. Under Actions:

  • Download Report downloads the same report as the results page.
  • Undo removes the invoices an import created. It is offered for 7 days after the import completes. See Undo an invoice import.

Click Refresh to update the list, and use Per page and the arrows to page through older imports.

Errors and warnings

Errors block the import. Proceed to Import stays disabled (it reads Fix Errors First) until there are none. Common errors:

  • A required value is empty, or a number or date is not valid.
  • Customer not found. "Customer "X" not found in QuickBooks. Invoice will fail to import." The name must match the customer's display name in QuickBooks. Case and surrounding spaces are ignored.
  • Product/Service not found. For a sub-item, use the full path, for example "Parent:Child". A Category cannot be used on an invoice line.
  • Class or location not found, or class or location tracking is not turned on in QuickBooks.
  • Line Amount does not match. When Quantity, Unit Price and Line Amount are all mapped, Line Amount must equal Quantity × Unit Price rounded to the cent. The message shows the amount to use.
  • Negative invoice total. Line amounts can be negative, but each invoice's total must be $0.00 or more.
  • Invoice number already exists. "Invoice #N already exists in QuickBooks." The import only creates new invoices. To change existing invoices, use Replace invoices from a file or Change specific fields on invoices or items.

Warnings do not block the import. They appear in the Export Issues file with the severity "warning". For example, "Unable to validate customers - QuickBooks connection issue" means ClientSynq could not check customers, so rows with an unknown customer may still fail during the import.

Class tracking

The Map Your Fields page shows QuickBooks Class Tracking: followed by Invoice level, Line item level or Not enabled, read from your QuickBooks settings. Class is not in the field list. Instead, if your file has a column named Class, Class Name, Class Ref or Line Class, ClientSynq maps it to the level QuickBooks uses: one class for the whole invoice, or a class per line. When class tracking is not enabled, the column is not mapped. Class values must match existing classes in QuickBooks. See Use class tracking.

Field reference

Field Required Notes
Customer Yes Must match an existing customer's display name in QuickBooks.
Invoice Date No MM-DD-YYYY (YYYY-MM-DD also works). Defaults to today if not provided.
Invoice Number No Rows with the same number become one invoice. Must not already exist in QuickBooks. If you do not map it, each row becomes its own invoice and QuickBooks numbers it. ClientSynq records the number QuickBooks assigned, so Undo can still find the invoice.
Department/Location No Must match an existing location or department in QuickBooks. See Use location tracking.
Payment Terms No A term name from QuickBooks, for example Net 30. The due date follows from the terms.
Customer Email No One address, or several separated by commas or semicolons.
Email Status No NotSet, NeedToSend or EmailSent. Without a column, you can set one value for every invoice with -- Or set default --.
Custom field No Shows the name of your first QuickBooks sales custom field. Hidden when that field is turned off in QuickBooks.
Line Description No Up to 4,000 characters.
Line Amount Yes The line total. Must equal Quantity × Unit Price when all three are mapped.
Product/Service Yes Must match an existing product or service. Use "Parent:Child" for sub-items.
Quantity No 0 or more.
Unit Price No Price per unit. Can be negative.
Tax Code No For example TAX for taxable or NON for non-taxable.
Service Date No The date the service was performed.

Header values (customer, dates, number, terms, email, custom field, location) are read from the first row of each invoice.

For descriptions and examples of every QuickBooks invoice field, open the QBO Invoice Field Guide page in ClientSynq at /customer-portal/qbo-import/field-guide.