Invoice Sync Knowledge Base

for WooCommerce to QuickBooks Invoice Syncing

INITIAL Setup

Connecting To QuickBooks Online

Quick Start

Step 1: Go to QuickBooks online and sign into your account.

Step 2: Open a new tab, go to QuickBooks Developer portal, here: https://developer.intuit.com/app/developer/homepage

Step 3: Once you access the developer page, you should be asked to setup an account. You use the same login information as used for QuickBooks online.

Step 4: Follow this quick 15 second video on setting up a new app:

Step 5: Make sure you copy the Redirect URL, and place it in the new app you created, as shown in the video. To find the Redirect URI go into your Website with the plugin installed, Under “WooCommerce” → QuickBooks → “Accounts” Tab there will be a notice at the bottom with a notice: “To authorize your account you need to add the following URI to Redirect URI list of QuickBooks App:”

Grab the URI from there and input it as the #2 Link as shown in the video. Save. Follow Step 6. The Client ID and Client Secret Keys will also show up on this “Account” Page after you create an account in our plugin. The “accounts” you create here are where you configure the logic for what to sync into QB.

Step 6: Copy the Client ID and Client Secret keys, paste them in the account you created in the Invoice Sync Plugin.

Step 7: As a part of creating an account in step 6, there is a button in the account process in our Plugin which will ask you to authorize “Connect To QuickBooks” You will use the QuickBooks credentials to log into your regular QuickBooks account (not developer) At this point, your account will be connected and you won’t have to use the developer account for your regular operations.

Sync Status

Understanding the Sync Status

What is the Sync Status list?

The Sync Status shows a list of all orders queued or previously synced with the QuickBooks Online account. The orders showing in the list are based upon the Settings, refer to the Settings section: Select Order Status for Syncing. Based upon the WooCommerce Order status, orders will appear in the list for syncing.

Overview of the Sync Status Functionality & Table Data

Overview of the Sync Status Page by functionality & data field.

  • Last Synced (Green Box) – Shows the last time a sync event occurred with QuickBooks Online account.
  • Sync Now (Orange Box) – The Sync Now is a bulk order syncing functionality. If clicked, all orders not blocked will be sent to sync with the QuickBooks Online accounts setup for syncing. Note: If you use this function and have many orders queued for syncing to QuickBooks online, this action might time out. The QuickBooks API will often time out or throttle large volume of requests to their servers. If this occurs, please perform a Reset Background Process as outlined in the Settings section. This will end the process of syncing allowing for a new one. For best performance with the QuickBooks API servers, we’d recommend you only perform a bulk Sync Now on a single page at a time. Blocking out other orders to prevent overloading the QuickBooks API servers and causing a timeout.
  • Bulk Actions for Blocking Orders (Yellow Box) – The Bulk Actions allow you to enable or disable a block on a single order or group of orders that is checked. Blocking an Order will prevent an order from being sent to QuickBooks Online account for syncing, even if it’s matching the account settings to be a candidate for syncing. Once a blocked is applied, the red icon will show next to the order.
  • Single Sync (Purple Box) – The Single Sync is a syncing action that will only send the specific order to the QuickBooks Online account for syncing. Note: This is the recommend syncing action to perform for testing and verifying orders are being sync to the QuickBooks Online account.
  • Order column (Blue Box) – Shows the Order ID and customer name for the order in WooCommerce, clicking on the Order will load the order details page.
  • Account Name column (Black Box) – Shows the QuickBooks Online account name the order is syncing to based upon account settings configured.
  • Sync Errors column (Grey Box) – Shows any errors on the sync event. Refer to the Logs section for more information about error logs.
  • Order Status column (Brown Box) – Shows the WooCommerce current order status for the order.
  • Date column (Teal Box) – Shows the date the order was placed on your website.
  • Total column (Dark Blue Box) – Shows the order total paid by the customer at checkout and current order value in the order details page.
  • Search Navigation (Pink Box) – Search for an order ID or customer in the Sync Status list.
  • Page Navigation (Dark Purple Box) – Navigate by page on the Sync Status list.
  • Expand Navigation (Red Box) – Drop down on the order to expand more details about the accounts being synced and QuickBooks Online action status.

Syncing Options

How do my orders sync to QuickBooks?

Sync WooCommerce Orders based upon the 5 ways.

  • Schedule Sync – An automatic scheduled syncing configured on the QuickBooks Online Account settings, refer Sync Schedule under the Accounts section to define the schedule of Hourly, Daily or Weekly.
  • Sync Now – Instant on demand bulk order syncing functionality. If clicked, all orders not blocked will be sent to sync with the QuickBooks Online accounts setup for syncing.
  • Single Sync – Instant on demand syncing action that will only send the specific order “clicked for Single Sync” to the QuickBooks Online account for syncing. Note: This is the recommend syncing action to perform for testing and verifying orders are being sync to the QuickBooks Online account.
  • Force Sync Now – A syncing method that will override all settings configured for the account and send the order to the account selected to Force Sync against. Found under the Bulk Actions dropdown only available if multiple accounts are configured. Use caution when preforming a force sync, could have unintended consciences.
  • Order Sync Now – On the order details page, under QuickBooks Sync container, clicking “Sync Now” button performs a Single Sync action of the order to the accounts the order is configured to sync to in QuickBooks Online account.

Note: First Sync Behavior & Notification Banner

During this first sync, you can expect this first sync to your QuickBooks account to take an extended period of time and show the following progress bar.

Why? During the first time syncing, the Invoice Sync plugin will crawl your QuickBooks account and map the QuickBooks account to data mine the key data: remote_id, acccount_id, doc_number and other meta data required to sync invoices with WooCommerce to build a local database on your website, hence the message “Updating local database”. The duration to complete this mapping and local database creation step is fully dependent on the size of the QuickBooks account and number of entries to map. The process is performed in the background and will not interrupt your website activity. Our recommendation, allow this to run in the background and check back later for the progress bar to be completed. If the progress bar stays on for an extended period of time 3+ hours and you have only a few invoices in QuickBooks, QuickBooks servers, at times like normal APIs may timeout due to load and server performance. If this occurs, perform a sync again to continue the mapping process. After this initial local database is created, future syncing activity will be quick and fast to your QuickBooks account.    

Accounts

QuickBooks Online Integration with My Account

Add a New QuickBooks Account
  • Step 1: Add a New Account. Click the Add New button to setup your QuickBooks online account for syncing.
  • Step 2: Input Account Name, Client ID and Client Secret. Select either Production or Development for Account Mode. Development mode is used for testing purpose and verification of data syncing between WooCommerce Orders and QuickBooks Invoices. Use Production mode for syncing to your actual QuickBooks Online live account. For setting up Client ID and Client Secret, refer to QuickBooks Quick Setup Guide.
Customer ID Mapping

Select from 2 types of Customer mapping options

  • Master QuickBooks ID – Map all orders from WooCommerce to a single Customer in QuickBooks online. Once enabled, all Invoices created in QuickBooks online will be created under the same Customer ID in QuickBooks. Commonly used when Customer lookups are not required in QuickBooks or Guest orders.
  • User QuickBooks ID – After a Customer is created in QuickBooks, a user ID is generated for the Customer account. (user ID found in the URL of customer profile in QuickBooks Online web browser after “=” sign). In your WordPress WooCommerce website, under the Customer profile. Input the Customer ID under the profile field for QuickBooks Customer IDs. Now any orders placed by the customer will use the ID to map the WordPress WooCommerce Customer to the QuickBooks Online Customer.     
    • Select Customer Sync Settings by Email Address (New Feature 2021) If QuickBooks ID is not mapped to WordPress User, or Account is not yet created in QuickBooks. Customer creation and syncing to QuickBooks is possible from user information in WordPress. Account is created and orders synced to QuickBooks account based on email address match.

QuickBooks Customer Creation Options:

Auto-mapped Fields Upon Account Creation:

Note: QuickBooks ID will not automatically be filled out in WordPress User Profile after account creation. Orders will continue to sync from WooCommerce to QuickBooks Customer if email match is found. 

Order Sync Type

Define the Orders that will sync to the QuickBooks Online Account. You can select All or Select.

  • All – The all option will send all orders placed on your website to the QuickBooks Online account for invoice creation. Unless you define exceptions. The exceptions supported are by Order ID, by State or by Shipping Zone. If an order contains an exception it will not be sent to QuickBooks Online account for syncing.
  • Select – The select option requires you to define which orders placed on your website are sent to QuickBooks online for invoice creation. You can define the type of orders by Order ID, State, Shipping Zone or by Product meta date of Categories. Products or Attributes. If an order contains a defined order meta data value, the order will be sent to the QuickBooks Online account for invoice creation.
Invoice Creation Type

Define the invoice and payment functionality for QuickBooks Online Account

QuickBooks Invoice Numbers

  • Prefix Number – To avoid a number value conflict between WooCommerce Order Numbers and QuickBooks Invoice number, use this box to define a prefix number. The prefix number will be appended to the WooCommerce Order ID. If no prefix number is provided, the default WooCommerce Order ID will be used for creating an Invoice ID in QuickBooks Online Account

QuickBooks Actions

  • Statuses to Create Invoice – Define which WooCommerce order statuses will be used to create an invoice in QuickBooks Online account. For example, if selected “Processing” order status. An order with a “Processing” order status will have an invoice created in QuickBooks Online Account.
  • Statues to Mark Invoice Paid – Define which WooCommerce order statuses will be used to create a payment on an existing invoice in QuickBooks Online account. An invoice needs to be created before a payment will be made on the Customer account.

Note: If the Order ID exists in QuickBooks Online account already, a new invoice will not be created or new payment will not occur. The Order in WooCommerce will be marked as Invoice or Payment completed and will not update again. This prevents duplicate invoices or payments occurring on the same Orders. If you need to re-sync an invoice that has been deleted manually in QuickBooks, click the x button under the QuickBooks Sync module in the order details page:

QuickBooks Terms IDs Mapping

(Click Arrow ∧∨ Button To Display)
  • Map the WooCommerce order status to a QuickBooks Online payment term. After you have defined the Order Statuses that will be used to create an invoice in QuickBooks Online account, you will need to define the Payment Terms for the invoice. As a result, when the “Processing” order status creates an invoice, you need to define the Payment Terms for the invoice, for example “Net 30”. Now when the invoice is created, the Payment Terms will be set based upon the Order Status automatically.
  • Use the Update Term List button (After the account is connected to QuickBooks Online) to update the list of terms you have defined. If you update or modify the terms list set in QuickBooks Online account, make sure to update the term list and WooCommerce order status mapping.

Invoice Type

IMPORTANT: Product mapping is based upon the Product SKU number. The Product SKU number in WooCommerce Products MUST match the Product SKU number in your QuickBooks product. If the SKU numbers are not matching, the product will not be added on the invoice created. An error log will be generated, indicating the SKU numbers for the Order ID are not matching and invoice can’t be created.

Note: At this time, the plugin will not create new products or sync products between WooCommerce Products and QuickBooks Online Products. You will be required to map the products prior to attempting to sync.

  • All Products – The all products option will create an invoice with all the products listed on the WooCommerce order to the Invoice in QuickBooks Online account.
  • Select Products – The option select products allows you to limit the products that are included upon invoice creation to only include the Categories, Products or Attributes you add to this field. For example, I have an order in WooCommerce with 2 products. Product X and Product Y. Under the option Select Products, I select only Product X. Now when the invoice is created in QuickBooks Online account, the invoice will only be created with Product X listed, Product Y will be excluded from the invoice created in QuickBooks Online.

Note: Using this option Select Products means the Order total amount will NOT MATCH the QuickBooks Online invoice created for the Order in WooCommerce. 

Product Price Mapping

Select from 2 price options:

  • Order Price – The order price is the price the customer paid on the order placed in WooCommerce.
  • Unit Price – Under the product details settings in WooCommerce products, we add a field labeled “Unit Price”. If you Input a unit price for the product and if Unit Price is selected, the product price cost in the QuickBooks Online invoice will list the Unit Price, NOT the order price paid by the customer in the WooCommerce order. Unit price is commonly used for Wholesale and Business to Business operations.

Note: If using Unit Price option, the invoice total value created in QuickBooks Online account will NOT MATCH the total value paid by the customer on the WooCommerce Order. 

Select Pricing Data

Determine the pricing data field mapping for the invoice in the QuickBooks Online account. If you want the WooCommerce Order to match the QuickBooks Invoice, all fields you use must be selected:

  • Shipping – Add the shipping cost to the invoice in QuickBooks Online account.
  • Discounts – Include the discount value on the invoice in QuickBooks Online account.
  • Taxes – Select the Tax value on the invoice in QuickBooks Online account.

Note: If a pricing data field is not selected and included in the invoice created in QuickBooks Online account, the value of the invoice in QuickBooks Online Account will NOT MATCH the order value in the WooCommerce Order. 

Taxes

Determine the tax name used for mapping taxes in QuickBooks Online Account. Both QuickBooks Online and WooCommerce have unique tax names that can be assigned to a tax applied on an order. To map taxes, select the tax name used for mapping and creating the invoice in QuickBooks Online account.

  • Customer QuickBooks Tax Name – Use the tax name set under the Customer profile for QuickBooks Online account under the Tax Info tab, Default tax code selection.
  • WooCommerce QuickBooks Tax Name – Use the tax name set under the WooCommerce > Settings > Taxes rate tables.
  • Master QuickBooks Tax Name – Use a tax name to apply to all invoices created in QuickBooks Online account

Note: Depending on the tax name selection, the WooCommerce order value and tax value applied to the customer on the Order will NOT MATCH the invoice created in QuickBooks Online account. By default, the WooCommerce order will apply the WooCommerce tax name based upon the taxes rate tables during order checkout. 

QuickBooks Tax Table

Import and sync a Tax Table to QuickBooks Online account tax tables.

  • CSV Format – The CSV format is required for syncing and creating the tax table in QuickBooks Online account, download CSV syntax sample
  • WooCommerce QuickBooks Tax Name – Use the tax name set under the WooCommerce > Settings > Taxes rate tables.

IMPORTANT: This feature is designed to create a new Tax table in QuickBooks if a Tax table is not currently created in QuickBooks Online account. If you have a Tax table already created in QuickBooks Online account, this feature will not sync the Tax rates between WooCommerce and QuickBooks Online Account or maintain changes or modifications. YOU are required to maintain and update the Tax rate according to your local tax laws and regulations. We are not responsible for maintaining or updating the Tax rates being applied to WooCommerce orders or taxes being applied on QuickBooks Online invoices for customers.

Note: Depending on the Tax table size and number of entries, the QuickBooks API may timeout due to the volume of entries to create in the QuickBooks Online account. If the timeout occurs, reset the background process and perform a new sync request. A new sync request will reset the API call and continue to sync and create the tax table. 

Sync Schedule

Define the Sync Schedule for the QuickBooks Account:

  • None – No automatic syncing will occur. All syncing will need to be performed by clicking the sync options of Single Sync, Order Sync, Sync now or Force Sync.
  • Hourly – A automatic syncing will occur hourly, any orders matching the account configuration settings above will be synced with the QuickBooks online account.
  • Daily – A automatic syncing will occur daily, any orders matching the account configuration settings above will be synced with the QuickBooks online account.
  • Weekly – A automatic syncing will occur weekly, any orders matching the account configuration settings above will be synced with the QuickBooks online account.

Refer to section Invoice Syncing Options to learn more about the options for syncing WooCommerce Orders to QuickBooks Online account.

Note: If you have defined a sync schedule, Hourly, Daily or Weekly you can still use the Single Sync, Order Sync, Sync Now or Force Sync functionality which will occur outside the defined Sync Schedule. 

LoGs

Using QuickBooks Logs for Information

Understanding Logs

QuickBooks Online API logs are important to understand and use to learn about the syncing behaviors occurring between WooCommerce Orders and QuickBook Online Accounts.

  • Event – The event is the sync action being performed or action occurring with the database.
  • Account Name (s) – This will indicate which QuickBooks Online account was used to perform a sync action.
  • Status – This will indicate the result of the sync action:
    • Success (Green): The order ID successfully synced with QuickBooks Online account
    • Not Synced (Yellow): The order ID was not matching the QuickBooks Online account settings configuration, a sync action did not occur
    • Error (Red): The order failed to sync with the QuickBooks Online account.
  • Order IDs – This will show the WooCommerce Order IDs attempted to sync with the QuickBooks Online account.
  • Details – This will show the details of the sync event that occurred. Refer to the section, Understanding error codes for more information about errors and recommended actions.
  • Date – The date and time the account sync occurred.
Common Log Entires, Errors and Recommended Actions

A list of common error logs and details.

  • Status – Success
    • Details: Blank
    • Recommendation. The order successfully synced to the QuickBooks Online account listed, verify the entry is listed in the QuickBooks Online account and matches based upon the account settings configured.
  • Status – Not Synced
    • Details: Orders not matching account settings: Orders are not allowed.
    • Recommendation. This is a common log indicating the order didn’t sync to the QuickBooks Online account because the settings configured on the Account section didn’t match the order information. If the order should have synced, refer to the account settings configured and order data to understand why the sync did not occur.
  • Status – Error
    • Details: The Status code is: 400 The Helper message is: Invalid auth/bad request (got a 400, expected HTTP/1.1 20X or a redirect) The Response message is: Required param missing, need to supply the required value for the APIRequired parameter Name is missing in the request
    • Recommendation(s). This is common with a QuickBooks Online API server times out. Try the following:
      • If using Schedule Sync or Sync Now, try sending a smaller volume of orders to sync to QuickBooks Online. The volume of orders may be too larger to process. Use the Block functionality to limit the number of orders being sent at a time or use the Single Sync action.
      • Due to traffic with QuickBooks Online Servers, this can occur and not controlled by the plugin. Wait a few hours and try again. Often waiting to a different time of day will solve this error and the load on QuickBooks Online Servers
      • If you are using a Firewall or Security plugin, verify the QuickBooks API calls are not being blocked or filtering. Whitelist the API Call to allow the syncing to occur.
      • Try to reauthorize the account. To perform syncing, you authorized the QuickBooks account to your WooCommerce website. At that time, a token is granted by QuickBooks API. The token can expire, performing a new authorization will reissue the token.
  • Status – Error
    • Details: “[Account Name]” is not authorized
    • Recommendation. This error indicates a QuickBooks Online account is setup under the Accounts tab, but the account is not authorized. To solve, authorize the account to perform syncing with the QuickBooks Online account.
  • Status – Error
    • Details: “[ID]”: SKU not matching.
    • IMPORTANT. As outlined in the Account settings configuration, the Product uses the SKU number to lookup and map to QuickBooks Online account and create an invoice. If the SKU numbers are not matching or not existing, the invoice will not be created until the SKU exist in QuickBooks Online account or the SKU mis-match is resolved. The SKU numbers between WooCommerce products and QuickBooks Online products are REQUIRED to match for a sync to be successful and invoice be created.
    • Recommendation. Review the Order ID identified and the Product ID SKU number and verify the number exist in QuickBooks Online. If it exists verify the numbers match. If it doesn’t exist add product SKU number to match.
  • Status – Error
    • Details: cURL error during making API call. cURL Error Number:[28] with error:[Operation timed out after 100001 milliseconds with 0 bytes received]
    • Recommendation(s). This is another common with a QuickBooks Online API server times out. Try the following:
      • If using Schedule Sync or Sync Now, try sending a smaller volume of orders to sync to QuickBooks Online. The volume of orders may be too larger to process. Use the Block functionality to limit the number of orders being sent at a time or use the Single Sync action.
      • Due to traffic with QuickBooks Online Servers, this can occur and not controlled by the plugin. Wait a few hours and try again. Often waiting to a different time of day will solve this error and the load on QuickBooks Online Servers
      • If you are using a Firewall or Security plugin, verify the QuickBooks API calls are not being blocked or filtering. Whitelist the API Call to allow the syncing to occur.
      • Try to reauthorize the account. To perform syncing, you authorized the QuickBooks account to your WooCommerce website. At that time, a token is granted by QuickBooks API. The token can expire, performing a new authorization will reissue the token.
  • Sync Errors (Sync Status Page) – Customer ID missing.
    • Recommendation(s). Add QuickBooks Customer ID into User field in WordPress.
      • If your account is configured to send the WooCommerce Order to a “User QuickBooks ID” in the account settings, the error “Customer ID missing” will occur if the QuickBooks ID is not input into the appropriate account field in the users profile on WordPress.

Orders Fail to Sync

Sync Status Progress Bar is Stuck On

When the Invoice Sync plugin is performing a sync to QuickBooks Online Account API, you may see the Sync Status Progress Bar.

This indicates a sync is in progress. If the Sync Status Progress Bar stays on for extended period of time or you see a message “QuickBooks syncing has been scheduled to run in the background Force Sync: Syncing to [name] Invoices. Updating local database. This indicates a potential API timeout has occurred. Refer to the logs to take appropriate actions. If no logs have been generated, refer to the Reset Background Process functionality, outlined under the Miscellaneous settings. Perform a reset to clear the active QuickBooks Online API sync. Now try the sync action again.

Settings

Setting up Global Settings for Invoice Sync

Select Order Status for Syncing
  • Define the WooCommerce Order Statuses that are eligible for Invoice Sync between WooCommerce and QuickBooks. Once the Order Status is selected, Orders eligible for syncing will show in the Sync status tab.
Defining emails for notifications

Email notification types can be setup: Success Event Log, Warning Event Log and Error Event Log. All events are stored in the Log tab with details on the event.

  • Success Event Log – An order has successfully synced with QuickBooks.
  • Warning Event Log – An order has synced with QuickBooks with warnings or required actions to review order data.
  • Error Event Log – An order has failed to sync with QuickBooks due to errors requiring actions for syncing to occur.
Miscellaneous Advanced Settings
  • Update Local Database – For syncing to operate, we update the local website database of mappings for orders sent to QuickBooks for syncing. Use this setting, if a failed sync occurs between QuickBooks and your Website.
  • Reset Background Process – The QuickBooks API servers due to load or downtime may not complete the syncing between your website and the QuickBooks sever. Resulting in the Background syncing to be active for a long time. If this occurs, use the Reset function to kill the API connection and perform a new syncing request.