QuickBooks Online

STEP 1: Setting Up Your Data

Zoey will not "Sync" or "Pull Over" your QuickBooks Products and Customers. So you will need to map them:

Mapping Products

Zoey Products will map to QuickBooks Products by SKU. If your Zoey SKU is going to be different from the QuickBooks SKU, you can add a Zoey Custom Attribute for the QuickBooks SKU and use the Mapping configuration when going through the setup below.


Zoey will create QuickBooks Products if not mapped

When an Order is being sent to QuickBooks, if the Product does not exist in QuickBooks, Zoey will create the Product.

Product FAQ:

  • Does Zoey sync my product inventory and prices? No, you must manage your inventory and prices in Zoey or with one of our file-based import/integrations.
  • When Zoey creates a product, which accounts does it assign to the product? You can configure "Default Accounts" in the Zoey configuration settings, see below.

Mapping Customers

Zoey will NOT pull-over your QuickBooks Customers. Zoey Accounts will MAP to QuickBooks Customers by matching the Zoey Account Name with the QuickBooks Customer "Display As" Name.


Zoey will create QuickBooks Customers & SubCustomers if not mapped

When an Order is being sent to QuickBooks, if the Customer does not exist in QuickBooks, Zoey will create the Customer and possibly a Sub-Customer.

  • Zoey Accounts will map to (or be created as) QuickBooks Customers AND the Zoey Customers that are assigned to an Account will map to (or be created as) QuickBooks Sub-Customers.
  • Stand-alone Zoey Customers will be mapped to (or be created as) QuickBooks Customers.

Customers FAQ:

  • Do I have to create customers for all my QuickBooks Customers? You SHOULD create a Zoey Account AND Customer for each Customer in QuickBooks that will have Orders created for them in Zoey. Otherwise you run the risk of Zoey unintentionally creating duplicate customers.
  • Why does Zoey create Sub-Customers for my existing Customers? Zoey's structure can have multiple customers per account. To keep track of this, we create a Sub-Customer in QuickBooks mapped to the Customer. For accounting purposes, all Sub-Customer invoices will roll-up to the Customer.

STEP 2: Install the QuickBooks Integration App on Zoey

Once installed you will be taken to the Zoey QuickBooks Configuration page which you can find anytime from the Integrations page in your Zoey Admin

STEP 3: Connect to QuickBooks


You must be a QuickBooks Administrator

In order to connect Zoey to QuickBooks you must have Administrator Permissions or be the Administrator of your QuickBooks Account.

Optional: Select the API Mode - You can connect to QuickBooks Production or Development (Not all QuickBooks Accounts have Development Mode)

  • Step 1: Click the Green Connect to QuickBooks button
  • Step 2: Use the pop-up window to allow Zoey to access your QuickBooks Account

STEP 4: Configure The Connection

Send Zoey Orders to QuickBooks Invoices

Zoey Orders will become QuickBooks Invoices. You can choose to create the QuickBooks Invoice immediately when the Order is submitted, or after the Order reaches a specific group of statuses.

2-Way Sync of Payments

Zoey will update QuickBooks Invoices as PAID if you are allowing your customers to Pay their open invoices through Zoey using a Credit Card.

Non-Product Line Items

You can map Discounts, Gift Card Discounts, Store Credit, Shipping and Additional/Surcharges to Line Items (QuickBooks Products). Discounts and Shipping, when set to No will map to the Totals fields on the Invoice.

Mapping Products and Customers

By default, Zoey will map Accounts and Customers using the QuickBooks Display As name to match the Zoey Account Name.

Zoey products will also be mapped to QuickBooks Products by SKU. You can change the settings for these mappings if you need to use a custom field in Zoey to match the QuickBooks Display As and SKU.

Default Accounts

Zoey needs to know default accounts for creating Products and Invoices. You can configure the default Income Account, COGS Account, and Discount Account.


Accounts must be configured correctly

Accounts must be configured to the correct Income, COGS or Discount Account or it may cause an error when you try to sync your Invoices.

Track Product Inventory will only be enabled if you have Inventory tracking available in your QuickBooks Account. This will NOT sync inventory to your products, instead it will reduce inventory in QuickBooks when an invoice is created.

Payment Method Mapping

Zoey Orders are created with different payment method options (i.e. Net Terms, Credit Card, Wire Transfer). In this section you can map those payment methods to QuickBooks Methods and Bank Accounts the funds will be deposited into. Be sure you select a Payment Method AND Account from the list for each payment method. Not Assigned payment methods may cause errors when importing.

Net Terms

Zoey has pre-defined Net Terms that you can assign to each Account (Net 30, 60, 90 etc...). This section allows you to map the Zoey Net Term to the QuickBooks Net Term for the Invoice. If you do not have a QuickBooks Term to match a Zoey Term, you can select Due On Receipt.


By Default, Zoey will send over the Tax dollar amount for the Order/Invoice. If you have QuickBooks "AST" enabled, this may overwrite the tax amount. You can also map Tax Rates in Zoey to Tax Rates in QuickBooks. If you are NOT collecting Tax, you can leave all the below settings to No.


Only New Orders Will Sync

Zoey will only sync New Orders starting from the moment you click Save after enabling the connection. We will not automatically Sync your order history or any orders created while the connection is disabled. You can manually sync Orders to QuickBooks using the troubleshooting steps below for re-syncing an Order.

Error Handling and Troubleshooting

Error Reports

You can view a list of Errors at the bottom of the Configuration page (see below). We also highly recommend that you enable Email Error reports and enter the email address you wand the reports sent to.

How to Re-Sync an Order

If your Order did not sync over due to an error and you believe you have resolved the error, you can navigate to Orders > Order List, select an order using the checkbox, then click Bulk Actions > Created QuickBooks Invoice. This will give you a success or error message if there is still an error preventing the sync.


Below are a list of common errors that you may encounter and how to resolve them.

Link Orders on Duplicate Document Number Error

When set to Yes, a Zoey Order that cannot create a QuickBooks Invoice because the Zoey Order Number already exists on a QuickBooks Invoice will be linked to the Invoice with that Zoey Invoice Number.

Order failed to sync to QuickBooks. The name supplied already exists.

This error means that the sync is using the Zoey Product SKU to find the QuickBooks product by Name but cannot find it. Change QuickBooks Field from Name to SKU.

Invalid Reference Id : Categories cannot be used in transactions.

This error occurs when a Zoey Order is attempting to sync to QuickBooks Online, but the type of one or more of the items is set as Category in QuickBooks Online. You can't use category items on Orders.

  • Action: create_invoice_from_order
  • Code: 2500
  • Message: Invalid Reference Id
  • Details: Invalid Reference Id : Categories cannot be used in transactions.