Summary

How to Configure and Use the QuickBooks Connector in wxrks

The QuickBooks connector connects wxrks to your QuickBooks company to create invoices and bills, track payments, and associate customer, product, and vendor identifiers with wxrks entities.

Audience and Permissions

This article is intended for administrators responsible for financial integrations. Configuration is available for Business or Enterprise accounts and may require account administrator permissions.

To configure the connector, you need:

A QuickBooks Online account and access to the Intuit Developer Portal.
A QuickBooks application with the com.intuit.quickbooks.accounting and com.intuit.quickbooks.payment permissions.
The application's Client ID and Client Secret.
Access to the financial accounts, customers, products/services, and vendors in the QuickBooks company.

Key Concepts

Concept	Where It Is Used	Purpose
Customer	Org Unit Billing	Links a wxrks Org Unit to a QuickBooks customer.
Product/Service	Org Unit Billing	Defines the item used on invoice lines.
Vendor	User payment information	Identifies the vendor who receives a payable.
Accounts Payable Account	QuickBooks configuration	Account used to record bills.
Expense Account	QuickBooks configuration	Account used to record payable expenses.
Purchase Order Custom Field Definition ID	QuickBooks configuration	Custom field that receives the invoice purchase order number.
Webhook Verifier Token	QuickBooks configuration	Validates notifications sent from QuickBooks to wxrks.

Configure the QuickBooks Application

Sign in to the Intuit Developer Portal.
Open the workspace where the application will be configured.
Create an application or open an existing application for wxrks.
Under Permission, enable: - com.intuit.quickbooks.accounting - com.intuit.quickbooks.payment
Under Keys and credentials, copy the Client ID and Client Secret.
In wxrks, open Settings > Account Settings > Finance > Payment Integrations, select QuickBooks, and continue to Create and Configure QuickBooks App Credentials.
Copy the Redirect URI displayed by wxrks.
In the QuickBooks application, open Settings > Redirect URIs, add the copied URI, and save.

Connect QuickBooks to wxrks

1. Save the Credentials

In Set Your Credentials, enter the Client ID and Client Secret, then select Save. wxrks saves the configuration and opens the authorization step.

2. Authorize the Company

In Grant QuickBooks Permission:

Select Authorize with QuickBooks.
Sign in to the correct QuickBooks account.
Authorize access to the company that will be synchronized.
Wait to be redirected back to wxrks.

Confirm that you selected the correct company before accepting. The credential is linked to your wxrks account and the authorized QuickBooks company.

3. Configure Accounts and the Webhook

After authorization, open the General tab in Configure QuickBooks Accounts.

Select the QuickBooks Accounts Payable Account.
Select the QuickBooks Expense Account.
Enter the QuickBooks Purchase Order Custom Field Definition ID. Use the Definition ID of the custom field that should receive the purchase order number.
In QuickBooks, open the application's webhook settings and copy the Verifier Token into QuickBooks Webhook Verifier Token in wxrks. The value must be a UUID v4.
Copy the QuickBooks Webhook URL displayed by wxrks and add it to the QuickBooks webhook configuration.
Select Save.
Select Test QuickBooks Connection to validate the authorization and selected accounts.

The account selectors load options from the QuickBooks chart of accounts. The test also checks QuickBooks IDs configured on Org Units. If an account is changed or becomes inactive in QuickBooks, update the selection in wxrks.

Authorization Renewal

The authorization granted by QuickBooks is valid for 101 days and is renewed while wxrks makes API calls. If there are no calls for more than 100 days, you must delete the QuickBooks configuration in wxrks and configure it again.

Link Org Units to Customers and Products/Services

There are two ways to create these links.

Configure an Org Unit Individually

Open Organizations > Units and select the Org Unit.
Open the Billing tab.
Under QuickBooks Customer ID, select the matching Customer.
Under QuickBooks Product/Service ID, select the matching item.
Save the Org Unit changes.

The selectors show active records loaded from QuickBooks. A Customer link is required to create invoices; the Product/Service identifies the item on invoice lines.

Match Org Units in Bulk

To review multiple Org Units at once:

Return to Settings > Account Settings > Finance > Payment Integrations > QuickBooks.
Open Synchronization > Org Units.
Select Load Suggestions.
Review the suggested Customer, match percentage, and Product/Service.
Enable Selected to Update only for the rows you want to save.
Adjust any incorrect suggestion and select Save Selected.

wxrks suggests matches based on name similarity without case sensitivity. Suggestions with 90% or higher confidence are preselected, but they should be reviewed before saving.

Link Users to Vendors

Select a Vendor Individually

Open Users and select the user.
Open the Billing and Languages tab.
Under Payment Information, select QUICKBOOKS as the payment method.
Under QuickBooks Vendor ID, select the matching Vendor.
Save the user's information.

Only active Vendors with a primary email address are considered for automatic matching. To create a payable in QuickBooks, the user must have the QuickBooks payment method and a valid Vendor ID.

Automatically Synchronize Vendor IDs

Open Settings > Account Settings > Finance > Payment Integrations > QuickBooks.
Open Synchronization > Vendors.
Select Run Vendor Sync.
Review the Synced (1) and Unmatched users (2).

Synchronization compares the primary Vendor email in QuickBooks with the user's email in wxrks and fills in the QuickBooks Vendor ID when it finds a match. Correct the email addresses or Vendor record in QuickBooks, then run the synchronization again to process unmatched items.

Financial Synchronization

Receivables from wxrks to QuickBooks

When a receivable is created in wxrks, it can be created automatically in QuickBooks when:

The integration is authorized.
The Org Unit has valid Customer ID and Product/Service ID values.
The receivable currency matches the default currency configured in the QuickBooks company preferences.
The receivable is not already linked to a QuickBooks invoice.

The wxrks purchase order number is sent to the custom field configured in Purchase Order Custom Field Definition ID. A receivable that already has a QuickBooks link is not created again (For further details, see How to manage the Finance Section).

Payables from wxrks to QuickBooks

When a payable is created for a user with the QUICKBOOKS payment method, wxrks can create a Bill in QuickBooks. The payable must have:

A numeric, valid, and active Vendor ID.
The QuickBooks payment method.
A currency matching the QuickBooks company's default currency.
Accounts Payable and Expense accounts configured in the connector.

For further details, see How to manage the Finance Section.

Payments from QuickBooks to wxrks

With the webhook configured, wxrks receives payment notifications:

When a linked invoice reaches a zero balance in QuickBooks, the corresponding invoice in wxrks is marked PAID.
When a linked Bill reaches a zero balance in QuickBooks, the corresponding payable in wxrks is marked PAID.

wxrks ignores notifications for entities that are not payments for invoices or bills linked to the same environment and QuickBooks company.

Cancel Invoices and Payables

When an invoice with a QuickBooks link is cancelled in wxrks, the corresponding QuickBooks invoice is voided and its amounts are zeroed.
When a payable with a linked Bill is cancelled in wxrks, the Bill is updated with zeroed amounts and a cancellation note is added to the Bill notes.
Records without a QuickBooks ID do not have a corresponding document to void in QuickBooks.

Cancelling a record in QuickBooks should not be confused with deleting the record in wxrks. Check the status in both systems after the operation.

Provisioning Through Automations

Administrators who use pipelines can automate entity provisioning in QuickBooks:

Use an HTTP action authenticated with the connected QuickBooks company to create a Vendor or Customer.
Extract the created ID and, when needed, the currency returned by QuickBooks.
Save the data in wxrks with the entity update action.

The fields that can be updated through this automation are limited:

Entity	Available Fields
User	`quickBooksVendorId`, `currency`
Org Unit	`quickBooksId`, `quickBooksProductServiceId`

For example, a Vendor creation automation can save the Vendor ID on a user, and a Customer creation automation can save the Customer ID on an Org Unit. The automation cannot change fields outside this list (For further details, see Getting Started with Pipelines in wxrks).

Troubleshooting

Problem	What to Check
You cannot save the financial configuration	Check Accounts Payable Account, Expense Account, Purchase Order Custom Field Definition ID, and a Verifier Token in UUID v4 format.
Authorization fails or returns an error in wxrks	Confirm the Client ID, Client Secret, application permissions, and Redirect URI exactly as displayed by wxrks.
The test reports that no QuickBooks IDs are configured	Configure Customer ID and Product/Service ID on the Billing tab of the Org Units that will use the integration.
The invoice is not created	Check the credentials, Customer, Product/Service, default currency, and whether the invoice already has a QuickBooks ID.
The payable is not created	Check the active Vendor, numeric Vendor ID, QUICKBOOKS payment method, financial accounts, and currency.
The record remains pending after a QuickBooks payment	Check the QuickBooks Webhook URL, the Verifier Token saved in wxrks, and the application's QuickBooks webhook configuration.
A Vendor does not appear in synchronization	The Vendor must be active and have a primary email address. Correct it and run Run Vendor Sync again.
An Org Unit suggestion is incorrect	Select the correct Customer manually, adjust the Product/Service, and leave Selected to Update disabled for rows that should not change.

Quick Reference

Task	Path
Configure the connector	Settings > Account Settings > Finance > Payment Integrations > QuickBooks
Test the connection	QuickBooks > General > Test QuickBooks Connection
Map an Org Unit	Organizations > Units > Org Unit > Billing
Map a user	Users > User > Billing and Languages > Payment Information
Synchronize Vendors	QuickBooks > Synchronization > Vendors > Run Vendor Sync
Suggest Customer and Product/Service matches	QuickBooks > Synchronization > Org Units > Load Suggestions
Validate incoming payments	Configure the QuickBooks Webhook URL and Verifier Token

wxrks - QuickBooks Connector