Integrating Alvys with QuickBooks Desktop involves three (3) primary steps: Connection, settings configuration, and mapping accounts. This article focuses on connection and settings configuration within Alvys.
Prerequisites before Configuring QBD Integration in Alvys
Before configuring the integration, ensure that your:
Integration Architecture is Verified
Sync Station is Designated
Administrative Software Access is Granted
Company File is Active
Chart of Accounts is Structured
💡 If any of these items are not set up, refer to the QuickBooks Desktop Prerequisites article before proceeding.
Connection
Navigate to the Alvys Integrations Page by clicking your username in the bottom-left corner and selecting Integrations, or by copying and pasting the following URL into your browser: https://app.alvys.com/#/manage/integrations.
From the list of integration types, select Accounting.
By default, the first subsidiary in your list is selected. If needed, choose a different subsidiary to add the integration to. Click the ✏ (edit) icon next to QuickBooks Desktop to open the integration dialog box.
Select the Auto Sync Checkbox then select the subsidiary you wish to add the integration to and click Save.
⚠️ The Integration must be completed for one subsidiary at a time. After configuring a subsidiary, return to the Integrations page and repeat these steps for any remaining subsidiaries.
In the Setup step, a link is provided to download the QuickBooks Desktop application. Typically, the user has already installed the application on the designated machine; however, if this has not been completed, click the download link to navigate to the QBD product website. There, you can input your product details to download, install, and activate the application.
Next step is to download the QuickBooks Web Connector (.QBWC)
The Web Connector is a small application that transfers data between the Alvys TMS and QuickBooks Desktop. Often, it is installed automatically alongside the QuickBooks Desktop application. If it is already present on your machine, you may skip this step; otherwise, click the link to access the official article and installation file for the latest version.
💡 The "One Connector" Rule: Never install the Web Connector on multiple machines for the same company file. This creates a "Conflict of Access" where two connectors/messengers try to write to the database at once, leading to "Record Locked" errors or duplicate transactions.
Navigate back to Alvys to download the QuickBooks Web Connector (QWC) file and save it in a known location.
The QWC file acts as a secure instruction sheet that tells the Web Connector how to communicate with Alvys. Without this file, the Web Connector cannot identify the correct application or provide the necessary credentials to bridge the data. Alvys generates a unique QWC file for each subsidiary being integrated. This file is required to register Alvys as a trusted service and contains the following unique identifiers:
Application Name: Identifies the connecting service as Alvys.
OwnerID: A unique identifier for the Alvys application itself, acting as a permanent reference for QuickBooks to recognize the authorized service.
FileID: A unique identifier for your specific QuickBooks Company File (.QBW), ensuring data is only exchanged with your actual business database.
💡 Remember to prevent connection failures, you must store your QuickBooks Company File (QBW), the QuickBooks Web Connector application (QBWC), and the Web Connector File (QWC) in the same environment:
Local Setups Keep the company file and the web connector file on the specific computer that runs QuickBooks and the Web Connector.
Hosted or Cloud Setups (e.g., Rightworks, Ace Cloud) Upload both files to your remote environment and ensure the web connector file is saved in the same folder as your company database.
Local Setups Keep the company file and the web connector file on the specific computer that runs QuickBooks and the Web Connector.
Hosted or Cloud Setups (e.g., Rightworks, Ace Cloud) Upload both files to your remote environment and ensure the web connector file is saved in the same folder as your company database.
Next open the QuickBooks Desktop application and open the Company file that you would like to integrate with Alvys. If you are already in another company simply switch to the specific company.
⚠️ The QuickBooks Desktop Company file must be open when adding the Web Connector file (QWC) to the Web Connector application (QBWC). If your organization has multiple subsidiaries or companies, ensure that QuickBooks Desktop is switched to the specific company you are currently integrating before adding the application. The specific QuickBooks company file must be open so the Web Connector knows exactly which database to link and can grant Alvys the permission to share data. Each subsidiary requires its own unique Web Connector file provided by Alvys; you cannot use the same file for two different applications.
Open the web connector that was installed.
💡 The QuickBooks web connector can be opened from the QuickBooks desktop application Simply go to the File menu in the top-left corner, select App Management and Click Update Web Services, this will open the web connector.
Click Add an application. This opens another window, navigate to the location of the QWC file you downloaded in Step 3, select it, and click Open.
⚠️ Adding the application takes a while to be completed. Please do not close the application while the process is running.
Once the process is complete, a new popup will appear to Authorize New Web Service. Select OK.
Select one of the options from “Do you want to allow this application to read and modify this company file?”. Click the radio button and then Continue.
💡 When the prompt appears within your QuickBooks client requesting access, you should select "Yes, always; allow access even if QuickBooks is not running."
Selecting this recommended setting ensures that transactions sync automatically whenever they are triggered in Alvys, even if the QuickBooks application is not open. As long as the computer is powered on, the data will flow through. If the computer is off, transactions will remain in a queue for up to seven (7) days. If the computer is not turned on within that window, the transactions will need to be re-triggered from Alvys to be processed.
Click Done, the Application will appear in the QuickBooks Web Connector window.
Navigate back to Alvys to copy the password (Step 4).
⚠️ Ensure this password is documented and saved in a secure location.
Select the checkbox next to the Application and you will be prompted to enter the password. Select Auto-Run and adjust the “Every-Min” interval if needed. Every-Min is the interval at which the queue will be read to update QuickBooks with the transactions from Alvys.
Click Update Selected and wait for the process to complete.
Verify Permissions In QuickBooks Desktop, navigate to Edit → Preferences → Integrated Applications → Company Preferences. Ensure the Alvys integration app is listed and that the checkbox for access is selected. This confirms that QuickBooks has authorized the connection and will allow data to flow from Alvy
Link the Company File Path Navigate back to Alvys, refresh the page, and proceed to the Account Settings section. Before completing the configuration, copy and paste the file path for your QuickBooks Desktop Company File (.QBW). This is the actual database where all your company data including customers, vendors, and the Chart of Accounts is stored.
To verify which company file you are using and its file path, open the QuickBooks Desktop application and press F2 on your keyboard (or press and hold the Fn key while tapping F2). The Product Information window will open. Look for the File Information heading to find the full path to your .QBW file. Copy this path and paste it into the text box in Alvys.
Configuration Settings
After successfully connecting to QuickBooks Desktop, you must configure which transactions are exported from Alvys and map those transactions to the appropriate accounts in QBD. These settings determine what data is sent, when it is sent, and how it appears in QuickBooks Desktop.
Transactions Type
There are two (2) transaction types available for synchronization:
Revenue This option determines whether revenue transactions are synchronized with QuickBooks Desktop. When enabled, income related financial data such as customer invoices will be exported to QBD.
Expense This option determines whether expense transactions are synchronized with QuickBooks Desktop. When enabled, cost related financial data such as driver pay and carrier bills will be exported to QBD.
💡 Your selection here takes precedence over all other configuration settings. These options determine the type of financial data that will be exported. Enable only the options you intend to export to QBD. Once selected, additional settings are available to further control how transactions are exported.
Ignore Driver Bills
This setting allows users to prevent the export of all driver bills, including company drivers and owner operators, to QuickBooks Desktop. When enabled, bills associated with drivers will not be exported, giving users greater control over which transactions are sent to QBD. This option is commonly enabled when driver pay is managed outside of QBD, such as through a payroll system or a separate driver settlement solution. Please note that even when this setting is enabled, external carrier bills, subsidiary carrier bills, and company expenses such as fuel and tolls may still be exported if those options are configured.
Single Bill for Driver Statement
This setting controls how driver bills for company drivers and owner operators are exported to QuickBooks Desktop. It is used to consolidate all charges and transactions related to a driver, including trips, fuel, tolls, and other expenses, into a single bill per driver statement.
When this setting is enabled and a driver paystub or statement is generated, a single bill is exported to QBD for the total net amount of the paystub. All components of driver pay are consolidated into this bill, including trip pay, accessorials, deductions, credits, reimbursements, and any other adjustments. Each component appears as a separate line item on the bill, providing detailed visibility while keeping the accounting export grouped into one transaction. This option is commonly used when driver pay is processed on a scheduled basis, such as weekly or biweekly payroll cycles.
When this setting is disabled, generating a customer invoice will also export the driver bill for the individual trip. Each trip or delivery is exported as a separate bill. When a paystub is generated, multiple bills are exported for each transaction type on the paystub, including separate bills for credits, deductions/reimbursements.
Generate Carrier Invoice Separately
This setting applies to brokerage-type trips where an external carrier and its assets are assigned to a load. When enabled, the system verifies the presence of an uploaded carrier invoice before exporting the carrier bill to QuickBooks Desktop. Specifically, once a brokerage trip is marked as delivered or released and a user uploads a document categorized as a "carrier invoice," the system initiates the export of the carrier bill to QuickBooks Desktop.
This export can also be triggered when a user generates a customer invoice for a load. At that stage, the system checks for an uploaded carrier invoice; if no such document is found, the carrier bill will not be exported. Consequently, this setting should only be enabled if your workflow requires a carrier invoice to be on file prior to exporting external carrier bills for payment.
If this setting is disabled, generating a customer invoice for a trip involving an external carrier will automatically export the carrier bill to QuickBooks Desktop, regardless of whether the carrier invoice has been uploaded.
💡If this setting was previously enabled but no carrier invoice was uploaded, the carrier bill was not created and, as a result, was not exported to QuickBooks Desktop. To resolve this, upload a document of the "Carrier Invoice" type to the trip and then select "Regenerate Invoice." This action will generate the carrier bill and initiate the export process to QuickBooks Desktop.
Process Statement by Tax Category
When enabled, only bills for 1099 drivers are exported to QuickBooks Desktop. Bills for W-2 drivers are excluded, allowing users to manage W-2 driver payments through a separate payroll system. When disabled, bills for both W-2 and 1099 drivers are exported to QuickBooks Desktop. This setting is typically enabled by tenants who handle W-2 driver compensation outside of QuickBooks and want to prevent those bills from being synchronized while still exporting 1099 driver expenses.
⚠️ Some settings must be used in conjunction with one another, while others should not be enabled simultaneously. Please refer to the “Configuration Dependencies and Incompatible Settings” sections of this article for further guidance.
Pay Subsidiary Carrier
This setting applies to trips involving a subsidiary carrier (i.e., a carrier operating under a subsidiary of the main company) that is assigned alongside the tenant’s internal assets. By default, when a driver statement is generated and assuming the Single Bill for Driver Statement setting is enabled, a bill is exported for the tenant’s driver on the trip.
When Pay Subsidiary Carrier is enabled, this behavior changes: instead of exporting a bill for the driver when a paystub is generated, the system exports a bill for the subsidiary carrier when the load invoice is generated.
⚠️ Certain settings are mutually exclusive and should not be enabled at the same time. The Pay Subsidiary Carrier setting should not be configured together with the Single Bill for Driver Statement setting. Refer to the Configuration Dependencies and Incompatible Settings section for guidance.
Ignore Zero Valued Transactions
When enabled, this setting excludes invoices and bills with a total financial value of zero, meaning transactions that have no overall impact on the accounts will not be exported.
⚠️ If the Ignore Zero-Valued Transactions setting was previously enabled when a transaction with a total value of $0 was generated (such as a customer invoice), an issue may occur if that transaction is later updated to a value greater than $0. When attempting to export the updated transaction to QuickBooks Desktop, the system may encounter an edit sequence error: "The string [id] Edit Sequence is too long.” If you encounter this error, please contact Alvys Support for further assistance.
Create Vendor Using 1099 Tax Company
The “Create Vendor Using 1099 Tax Company” setting allows users to determine whether vendors should be created in QuickBooks Desktop using the tax company details (Tax Company Name and Address) specified in the Tax Information section of the Alvys driver profile (for either company drivers or owner-operators with the tax category of 1099).
When this setting is enabled:
If the vendor does not exist in QBD, a vendor will be automatically created when the driver statement is generated, using the Tax Company Name as the vendor's name and the Tax Company Address as the vendor address.
If the vendor already exists in QBD, the user must ensure that the vendor's name matches the Tax Company Name specified in the Alvys driver profile to avoid conflicts and create duplicates.
Carrier Statements
This setting must be enabled to export carrier statements as bills when generating a Carrier Statement from the Carrier Settlements module.
If you use the Carrier Settlements module to generate statements for external carriers and want these statements automatically exported to QuickBooks Desktop upon generation, this setting must be enabled. This is the only scenario in which this option should be turned on.
If you do not use the Carrier Settlements module and prefer carrier statements to be exported only when a carrier invoice is manually uploaded for a trip, this setting should be disabled, and the option to generate carrier invoices separately should be enabled.
Alternatively, if you prefer carrier statements to be exported only when the customer invoice is generated on a load, this setting should also be disabled, and the option to generate carrier invoices separately should remain disabled.
Export Company Fuel Expense
The TMS allows users to record fuel transactions, either manually or imported directly from the fuel provider. These transactions can be viewed in the Alvys Fuel Report.
In the fuel report, if a transaction is marked “Deduct Transaction” true, the cost will be deducted from the linked driver during payroll (statement generation). If it is not deducted, Deduct Fuel false (-), the transaction is treated as a company expense.
When the “Export Company Fuel Expense” setting is enabled, fuel transactions where Deduct Fuel is set to false (-) (i.e., fuel costs not deducted from drivers) are exported to QuickBooks Desktop as bills. This allows the company to track and manage fuel expenses that are not charged back to drivers, such as those incurred by company-owned vehicles. These exports are scheduled to occur daily at 6:30 AM UTC.
⚠️ Please note: if a user was not previously configured to export company fuel transactions and later enables this setting, past transactions will not be exported automatically. Additionally, if an export fails for any reason, contact Alvys Support to have those transactions exported.
Export Company Toll Expense
The TMS allows users to record toll transactions, either manually or imported directly from the toll provider. These transactions can be viewed in the Alvys Toll Report.
If a transaction is marked “Deduct Toll” true, the cost will be deducted from the linked driver during payroll. If it is not deducted, Deduct Toll false (-), the transaction is treated as a company expense.
When the “Export Company Toll Expense” setting is enabled, toll transactions where Deduct Toll is set to false (i.e., toll costs not deducted from drivers) are exported to QBD as bills. This allows the company to track and manage toll expenses not charged to drivers, such as those incurred by company-owned vehicles. Exports are scheduled daily at 7:30 AM UTC.
Subsidiaries
Alvys subsidiaries can be mapped directly to QuickBooks Desktop (QBD) Classes. This integration allows you to categorize every transaction by entity, enabling you to generate specific Profit and Loss reports and track the financial health of each subsidiary within QuickBooks Desktop.
In QuickBooks Desktop, Classes act as departmental filters. They are used to track income, expenses, and transactions at a more detailed level than just the Chart of Accounts. When you map an Alvys subsidiary to a QBD Class, every invoice or bill associated with that subsidiary in Alvys will automatically carry that Class designation in your QuickBooks company file.
Prerequisites Before Mapping Subsidiaries in Alvys
Before you can map your subsidiaries in Alvys, you must prepare your QuickBooks Desktop file. Follow these steps to ensure the systems synchronize correctly:
Enable Class Tracking in QBD:
Open QuickBooks Desktop and go to the Edit menu, then select Preferences.
Select Accounting from the left sidebar and go to the Company Preferences tab.
Check the box for Use class tracking for transactions.
Create Your Classes in QBD:
In QuickBooks Desktop, go to the Lists menu and select Class List.
Click the Class button at the bottom and select New.
Enter the names of your subsidiaries exactly as you want them to appear in your QBD reports.
Learn more about setting up classes in QuickBooks Desktop:
How to Map Alvys Subsidiaries to Classes
Select the Subsidiaries checkbox, which will create an additional step called Subsidiaries.
Click on the Subsidiaries step.
Proceed by mapping each specific subsidiary to the corresponding option presented in the right-hand dropdown menu.
Fleets
If your company prefers to track financial performance by driver groups or asset types rather than by legal entity, you can map Alvys fleets directly to QuickBooks Desktop (QBD) Classes. This integration allows you to monitor the revenue, costs, and overall profitability of each individual fleet within QuickBooks Desktop.
How to Map Alvys Fleets to Classes:
Select the Fleets checkbox, which will create an additional step called Fleets.
Click on the Fleets step.
Proceed by mapping each specific fleet to the corresponding option presented in the right-hand dropdown menu.
⚠️ Please note that you must choose between mapping by Subsidiary or by Fleet. These settings are mutually exclusive; the system does not support enabling both simultaneously. Select the option that best aligns with how your company tracks departmental profitability.
Shared Billing/Intercompany Billing
Shared Billing is used when a load is invoiced by one subsidiary (Invoice As) and tendered by another subsidiary (Tender As), and both subsidiaries have separate accounting integrations. This setting ensures that all financial transactions are correctly recorded across the two subsidiaries.
Invoice As Subsidiary (e.g., Alvys Motor)
Creates a customer invoice for the load
Creates an intercompany bill to the Tender As subsidiary (Alvys Motor 2) for the carrier/driver cost
Tender As Subsidiary (e.g., Alvys Motor 2)
Creates an intercompany invoice back to the Invoice As subsidiary (Alvys Motor)
Creates a vendor bill to the carrier or driver for the load
⚠️ Shared Billing must be enabled on both subsidiaries. Without it, the intercompany transactions will not export correctly.
Configuration Dependencies and Incompatible Settings
Some Configuration settings in the Alvys QBD integration are mutually exclusive (meaning they cannot be enabled at the same time) or render others inactive when enabled. In addition, certain settings may not require configuration at all, depending on the initial selection of Revenue and or Expense transactions
The Revenue Checkbox
If only the Revenue transaction checkbox is selected (customer invoices, etc.), do not configure any settings related to Expenses, including:
Single Bill for Driver Statement
Generate Carrier Invoice Separately
Process Statement by Tax Category
Pay Subsidiary Carrier
Create Vendor Using 1099 Tax Company
Ignore Driver Bills
Carrier Statements
Export Company Fuel Expense (not deducted from a driver)
Export Company Toll Expense (not deducted from a driver)
Single Bill for Driver Statement
Do not configure this setting with:
Ignore Driver Bills
Pay Subsidiary Carrier
Why: Single Bill for Driver Statement assumes that driver bills are being created and exported. If driver bills are ignored (not sent to QBD) this consolidation logic no longer applies and will conflict with the export process. Also, if configured with pay subsidiary carrier bills, the single bill for driver statement will take precedence.
Process Statement by Tax Category
Configuration Dependency:
Single Bill for Driver Statement must be enabled along with this setting
Do not configure this setting with:
Ignore Driver Bills
Pay Subsidiary Carrier
Why: This setting depends on driver bill data to separate payments by tax type. If driver bills are ignored or billing is redirected to a subsidiary carrier, tax-based filtering cannot function correctly.
Pay Subsidiary Carrier
Do not configure this setting with:
Single Bill for Driver Statement
Process Statement By Tax Category
Create Vendor Using 1099 Tax Company
Ignore Driver Bills
Why: When this setting is enabled, billing responsibility shifts away from the driver entirely. Any configuration that assumes driver-based billing, or driver vendor creation becomes invalid.
Ignore Driver Bills
Do not configure this setting with:
Single Bill for Driver Statement
Process Statement By Tax Category
Create Vendor Using 1099 Tax Company
Why: Each of these settings relies on driver bills being generated and exported. Ignoring driver bills removes the underlying data required for these settings to work.
Create Vendor Using 1099 Tax Company
Configuration Dependency:
Single Bill for Driver Statement must be enabled along with this setting
Do not configure this setting with:
Pay Subsidiary Carrier
Ignore Driver Bills
Why: This option assumes driver-based billing based on tax category. If billing is redirected to a subsidiary carrier or driver bills are excluded, vendor creation using tax data is no longer applicable.
Recommended Settings by Operational Type (Carriers)
Carrier Specific Recommendations
Typically Enabled Settings:
Revenue
Expense
Single Bill for Driver Statement
Export Company Fuel Expense
Export Company Toll Expense
From the perspective of an asset-based carrier, the priority is to simplify high volume payroll and manage fleet overhead. Enabling Single Bill for Driver Statement is essential because it prevents QuickBooks Desktop from becoming cluttered with hundreds of individual trip bills. Instead, it aggregates a driver’s entire work cycle (including base pay, fuel deductions, and toll reimbursements) into one clean, reconcilable transaction. Activating Company Fuel and Toll Expenses ensures that overhead costs not charged to drivers are still captured in your financial reports, providing an accurate view of your fleet's true operating margin and equipment costs.
Broker Specific Recommendations
Typically Enabled Settings:
Revenue
Expense
Generate Carrier Invoice Separately
From the perspective of a brokerage, financial accuracy depends on a strict verification process between the customer invoice and the third-party carrier’s billing. Enabling Generate Carrier Invoice Separately acts as a critical safeguard; it ensures that a carrier bill is never exported to QuickBooks Desktop for payment until the physical carrier invoice has been received and verified in Alvys. This prevents premature payouts and ensures that the expenses recorded in your accounting system exactly match the documentation provided by your external carriers.
FAQS
Q: Where do I find the Company File Path for the .QBW file?
A: Open QuickBooks Desktop and press F2 (or Fn + F2) to open the Product Information window. Look for the File Information section to find the full path. Copy and paste this entire path into the Account Settings in Alvys.
Q: Does the QuickBooks Company File need to be open when I click "Add an Application"?
A: Yes. QuickBooks Desktop must be open and logged into the specific company you are trying to link. The Web Connector needs to "see" the open file to establish the secure connection and grant Alvys permission to share data.
Q: What if the "Authorize New Web Service" popup doesn't appear after I select the .QWC file?
A: Check your Windows taskbar to see if the popup is hidden behind another window. If it still doesn't appear, ensure you are logged into QuickBooks as the Admin and are in Single User Mode, as restricted permissions can block the authorization prompt.
Q: Can I connect multiple subsidiaries to QuickBooks Desktop?
A: Yes. However, each subsidiary must be configured one at a time. After completing the setup for your first subsidiary, return to the Integrations page to repeat the process for any remaining subsidiaries. Note that each subsidiary requires its own unique Web Connector file (.QWC).
Q: Can I install the QuickBooks Web Connector on multiple computers?
A: No. You must follow the One Connector Rule. Installing the Web Connector on more than one machine for the same company file causes a "Conflict of Access," which results in duplicate transactions and record-locking errors.
Q: What happens if my computer is turned off when a transaction is triggered?
A: Transactions will stay in a queue for up to seven (7) days. As soon as the computer is turned on and the Web Connector runs, the data will sync. If the computer remains off longer than seven days, you will need to manually re-trigger the transactions from Alvys.
Q: Why should I select "Yes, always; allow access even if QuickBooks is not running"?
A: This setting allows Alvys to sync data automatically in the background. If you do not select this, you would be required to have the QuickBooks application open and active on your desktop every time a sync occurs.
Q: Can I export only revenue transactions without expenses (or vice versa)?
A: Yes. If you only select the Revenue checkbox, only customer invoices will export. If you only select Expense, only bills and driver settlements will export. You should only enable and configure the transaction types you intend to use.
Q: Can I map my transactions by both Subsidiary and Fleet?
A: No. These settings are mutually exclusive. You must choose whether you want to track profitability in QuickBooks Desktop by Subsidiary or by Fleet, as the system does not support enabling both at the same time.
Q: What should I do if I get an "Edit Sequence" error?
A: This usually happens if a transaction was originally synced as a $0 value (with the "Ignore Zero-Valued Transactions" setting on) and was later updated to a higher value. If you see this error, please contact Alvys Support for assistance.
Q: Why is a carrier bill not exporting to QuickBooks?
A: If Generate Carrier Invoice Separately is enabled, Alvys will hold the export until a document categorized as a "Carrier Invoice" is uploaded to the trip. The bill will not be created in QuickBooks until that document is present.
Q: Can I use "Classes" for tracking in QuickBooks Desktop?
A: Yes. Alvys allows you to map your Subsidiaries or Fleets to QuickBooks Classes. This allows you to run Profit and Loss reports by department or fleet. You must enable "Class Tracking" within your QuickBooks Company Preferences before mapping these in Alvys.
Next Steps
⏭️ Now that you have established a secure connection and configured your operational settings, you are ready to finalize the integration.
Proceed to QuickBooks Desktop: Account Mappings to link your Alvys revenue and expense categories to your QuickBooks Chart of Accounts. This ensures all synced data is recorded in the correct financial accounts.
Return to Collection
📁 Need to see the full list of articles? Return to the QuickBooks Desktop Collection.