Toweringmedia Extension Docs

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Magento 2 QuickBooks Connector – User Guide ======

===== Extension Overview =====

The **Toweringmedia QuickBooks Connector for Magento 2** connects your Magento 2 store with **QuickBooks Online** and automates the synchronization of customers, products, inventory, orders, invoices, payments, refunds, and credit memos.

The extension uses secure **Intuit OAuth 2.0 authentication** and provides bidirectional synchronization between Magento and QuickBooks Online. It also includes queue-based background processing, automatic retries, synchronization logs, admin retry tools, cron scheduling, bulk synchronization, and CLI commands.

===== Product Information =====

  * **Product Name:** Toweringmedia QuickBooks Connector for Magento 2
  * **PHP Compatibility:** PHP 8.1, 8.2, and 8.3
  * **QuickBooks:** QuickBooks Online
  * **Authentication:** Secure Intuit OAuth 2.0
  * **Synchronization:** Bidirectional Magento ↔ QuickBooks Online
  * **Installation:** Composer or Manual installation
  * **Additional Dependencies:** No additional dependencies required
  * **Processing:** Queue-based background processing with Magento Cron
  * **Supported Data:** Customers, Products, Inventory, Orders, Invoices, Payments, Refunds, and Credit Memos

===== Key Features =====

  * Bidirectional synchronization between Magento 2 and QuickBooks Online
  * Secure Intuit OAuth 2.0 authentication
  * Support for QuickBooks Online Sandbox and Production environments
  * Customer synchronization between Magento and QuickBooks
  * Product synchronization between Magento and QuickBooks
  * Inventory synchronization with export, import, or two-way synchronization
  * Order synchronization from Magento to QuickBooks
  * Invoice synchronization
  * Payment synchronization
  * Refund synchronization
  * Credit memo synchronization
  * Import QuickBooks customers and products into Magento
  * Support for Simple, Configurable, Virtual, Service, Bundle, and Grouped products
  * Configurable conflict resolution policies
  * Automatic and manual synchronization options
  * Bulk synchronization for customers, products, and orders
  * Queue-based background processing
  * Automatic retry for failed synchronization operations
  * Stale-lock recovery for queue processing
  * Detailed synchronization operation logs
  * Admin functionality to retry failed synchronization operations
  * Configurable cron schedules and batch sizes
  * CLI commands for synchronization, imports, status checks, and recovery
  * Magento Cron integration for automated synchronization
  * Built using Magento 2 native architecture without core overrides
  * Optimized queue-based architecture for high-volume stores
  * QuickBooks Desktop QBWC foundation included, with full QBXML synchronization planned

===== Installation =====

Please refer to the installation guide in the following article [[https://toweringmedia.com/installation|Installation Guide]].

===== Admin Tools =====

The **Admin Tools** section provides administrators with tools to manage and monitor the QuickBooks synchronization process from the Magento 2 Admin Panel.

The available tools allow administrators to:

  * View synchronization status
  * Monitor synchronization operations
  * Review synchronization logs
  * Identify failed synchronization operations
  * Retry failed synchronization operations
  * Run manual synchronization
  * Import data from QuickBooks Online
  * Export Magento data to QuickBooks Online
  * Perform bulk synchronization
  * Check queue processing status
  * Manage synchronization settings
  * Review synchronization errors and troubleshooting information

===== Validation Checklist =====

  * Verify that the QuickBooks Connector is installed and enabled successfully.
  * Verify that the Magento Cron is configured and running correctly.
  * Verify that the QuickBooks Online account is connected successfully.
  * Verify that OAuth authentication is working correctly.
  * Verify customer synchronization between Magento and QuickBooks.
  * Verify product synchronization between Magento and QuickBooks.
  * Verify inventory synchronization.
  * Verify order synchronization.
  * Verify invoice synchronization.
  * Verify payment synchronization.
  * Verify refund synchronization.
  * Verify credit memo synchronization.
  * Verify that synchronization logs are generated correctly.
  * Verify that failed synchronization operations can be retried.
  * Verify that bulk synchronization works correctly.
  * Verify that synchronization errors are displayed correctly in the Magento Admin Panel.
  * Verify that data synchronized to QuickBooks matches the corresponding Magento data.

===== Setup Instructions =====

After installing the QuickBooks Connector, configure the extension from the Magento 2 Admin Panel.

Log in to the Magento 2 Admin Panel and navigate to:

**Stores → Configuration → Towering Media → QuickBooks Connector**

The configuration page contains several sections that allow administrators to connect Magento with QuickBooks Online and configure synchronization behavior.

==== 1. General Configuration ====

Under the **General** section, configure the basic connector settings:

  * **Enable Connector:** Enable or disable the QuickBooks Connector.
  * **Connector Type:** Select the QuickBooks platform you want to connect with. For QuickBooks Online, select **QuickBooks Online**.
  * **Connection Profile Scope Mode:** Select the scope at which the QuickBooks connection profile should be managed.
  * **Default Sync Direction:** Select the default synchronization direction.
  * **Default Conflict Policy:** Define how conflicts should be handled when Magento and QuickBooks contain different data.
  * **Log Retention Period:** Specify how long synchronization logs should be retained.

==== 2. QuickBooks Online Configuration ====

The **QuickBooks Online** section contains the credentials and connection settings required to connect Magento with QuickBooks Online.

Configure the following:

  * **Client ID:** Enter the Client ID provided by Intuit.
  * **Client Secret:** Enter the Client Secret provided by Intuit.
  * **Redirect URI:** Use the redirect URI displayed by the extension when configuring the Intuit application.
  * **Environment:** Select the appropriate environment, such as **Sandbox** for testing or **Production** for the live QuickBooks account.
  * **Realm / Company ID:** This is populated after the QuickBooks account is connected.
  * **Token Status:** Displays the current OAuth connection status.
  * **Default Income Account ID:** Enter the QuickBooks income account ID to be used for synchronization.
  * **Default Expense Account ID:** Enter the QuickBooks expense account ID where required.
  * **Shipping Item ID:** Specify the QuickBooks item used for shipping charges.
  * **Payment Method Deposit Account Mappings:** Configure the QuickBooks deposit account mapping for Magento payment methods.

After entering the required QuickBooks credentials, click **Connect to QuickBooks** to authorize the Magento store with your QuickBooks Online account.

==== 3. Field Mapping ====

The **Field Mapping** section allows Magento fields to be mapped to QuickBooks fields.

The available mappings include:

  * **Customer Field Mappings (JSON):** Define customer field mappings between Magento and QuickBooks.
  * **Product Field Mappings (JSON):** Define product field mappings.
  * **Invoice Line Field Mappings (JSON):** Define mappings for invoice line-item data.

Use valid JSON format when entering custom field mappings.

==== 4. Tax Mapping ====

The **Tax Mapping** section allows Magento tax information to be mapped to QuickBooks.

Configure:

  * **Default QuickBooks Tax Code ID:** Set the default QuickBooks tax code.
  * **Tax Class Mappings (JSON):** Map Magento tax classes to QuickBooks tax codes.
  * **Tax Rate Mappings (JSON):** Map Magento tax rates to the corresponding QuickBooks tax rates.

==== 5. QuickBooks Desktop ====

The **QuickBooks Desktop** section provides configuration options for QuickBooks Desktop/QBWC integration.

Where applicable, configure:

  * **Application Name**
  * **QWC Username**
  * **QBC Password / Shared Secret**
  * **QBWC Endpoint URL**
  * **Enable QBWC Polling**

QuickBooks Desktop/QBWC functionality should only be configured when the corresponding QuickBooks Desktop integration is being used.

==== 6. Sync Schedule ====

The **Sync Schedule** section controls the background synchronization process.

Configure:

  * **Enable Cron Dispatch:** Enable or disable automatic queue processing through Magento Cron.
  * **Dispatch Interval:** Define how frequently pending synchronization operations should be dispatched.
  * **Max Operations Per Run:** Set the maximum number of synchronization operations processed during each run.
  * **Dispatch Products / Items:** Enable product synchronization processing.
  * **Dispatch Inventory:** Enable inventory synchronization processing.
  * **Dispatch Customers:** Enable customer synchronization processing.
  * **Dispatch Orders:** Enable order synchronization processing.
  * **Dispatch Invoices:** Enable invoice synchronization processing.
  * **Dispatch Payments:** Enable payment synchronization processing.
  * **Dispatch Refunds:** Enable refund synchronization processing.
  * **Dispatch Credit Memos:** Enable credit memo synchronization processing.

Ensure that Magento Cron is configured and running correctly on the server for scheduled synchronization to work.

==== 7. Inbound Import ====

The **Inbound Import** section controls importing data from QuickBooks into Magento.

Available settings include:

  * **Enable Customer Import:** Enable importing customers from QuickBooks.
  * **Enable Product Import:** Enable importing products from QuickBooks.
  * **Inbound Import Conflict Policy:** Select how conflicts should be handled when imported QuickBooks data already exists in Magento.

==== 8. Entity Sync ====

The **Entity Sync** section controls which Magento entities are exported to QuickBooks.

Configure the following options as required:

  * **Enable Product Export (Magento → QuickBooks)**
  * **Bundle / Grouped Export Strategy**
  * **Enable Inventory**
  * **Enable Customer Export (Magento → QuickBooks)**
  * **Enable Order Export (Magento → QuickBooks)**
  * **Enable Invoice Export (Magento → QuickBooks)**
  * **Enable Payment Export (Magento → QuickBooks)**
  * **Enable Refund Export (Magento → QuickBooks)**
  * **Enable Credit Memo Export (Magento → QuickBooks)**

==== 9. Automatic Synchronization ====

The **Auto-Sync** settings allow synchronization to occur automatically when Magento entities are created or updated.

Available options include:

  * **Auto-Sync Customers on Save:** Automatically queue customer synchronization when a customer is saved.
  * **Auto-Sync Products on Save:** Automatically queue product synchronization when a supported product is saved.
  * **Auto-Sync Orders on Save:** Automatically queue order synchronization when an order reaches an allowed status.
  * **Order Status Allowlist for Auto-Sync:** Define which order statuses can trigger automatic order synchronization.
  * **Auto-Sync Credit Memos on Save:** Automatically queue credit memo synchronization when a credit memo is created.

==== 10. Save Configuration ====

After completing the required settings, click **Save Config** in the upper-right corner of the configuration page.

The connector is now configured according to the selected synchronization settings.

==== Recommended Initial Setup ====

A typical initial setup sequence is:

  - Enable the connector.
  - Select **QuickBooks Online** as the connector type.
  - Configure the QuickBooks Online Client ID and Client Secret.
  - Select the appropriate QuickBooks environment.
  - Connect the Magento store to QuickBooks using **Connect to QuickBooks**.
  - Configure the default income, expense, shipping, payment, and tax mappings.
  - Configure the required field mappings.
  - Configure the synchronization schedule and Magento Cron.
  - Enable the required inbound imports and outbound entity synchronization.
  - Configure automatic synchronization according to the store's requirements.
  - Save the configuration.
  - Perform an initial synchronization and verify the synchronization logs.

===== User Experience =====

The **QuickBooks Connector** is designed to provide a simple and efficient experience for managing synchronization between Magento 2 and QuickBooks Online.

==== QuickBooks Connector Dashboard ====

The extension provides administrators with tools to manage the QuickBooks integration directly from the Magento Admin Panel. Administrators can configure the connection, control synchronization, review synchronization activity, and troubleshoot failed operations.

==== QuickBooks Connection ====

Administrators can connect the Magento store to QuickBooks Online using the **Connect to QuickBooks** option. The OAuth-based connection securely authorizes the Magento store to communicate with the selected QuickBooks company.

Once connected, the configuration displays the connection status and QuickBooks company information.

==== Synchronization Management ====

Administrators can control which Magento entities are synchronized with QuickBooks, including:

  * Customers
  * Products
  * Inventory
  * Orders
  * Invoices
  * Payments
  * Refunds
  * Credit Memos

Synchronization can be configured to run automatically through Magento Cron or triggered according to the configured synchronization settings.

==== Automatic Synchronization ====

When automatic synchronization is enabled, supported Magento entities can be added to the synchronization queue when they are created or updated.

For example:

  * A new customer can automatically be queued for synchronization.
  * A product update can automatically trigger product synchronization.
  * An order can be synchronized when it reaches a configured order status.
  * A new credit memo can automatically be queued for synchronization.

This reduces the need for administrators to manually synchronize individual records.

==== Synchronization Monitoring ====

Administrators can monitor synchronization operations and review logs from the Magento Admin Panel.

The synchronization information can help identify:

  * Successfully processed operations
  * Pending operations
  * Failed operations
  * Synchronization errors
  * Retry attempts

Failed operations can be retried after the underlying issue has been resolved.

==== Import and Export ====

The extension provides separate controls for importing data from QuickBooks and exporting Magento data to QuickBooks.

Administrators can configure inbound imports for customers and products and outbound synchronization for supported Magento entities.

==== Error Handling ====

When a synchronization operation fails, the administrator can review the available error information and take corrective action.

The queue-based processing and retry functionality helps ensure that temporary synchronization failures do not require the entire synchronization process to be restarted.

==== Recommended User Workflow ====

A typical administrator workflow is:

  - Configure the QuickBooks Connector.
  - Connect the Magento store to QuickBooks Online.
  - Configure account, tax, and field mappings.
  - Select the entities that should be synchronized.
  - Configure automatic synchronization and Magento Cron.
  - Perform an initial synchronization.
  - Review synchronization logs.
  - Resolve and retry any failed operations.
  - Monitor synchronization activity regularly.

===== Troubleshooting =====

The Troubleshooting section provides guidance for identifying and resolving common issues that may occur while using the QuickBooks Connector for Magento 2.

==== QuickBooks Connection Issues ====

If the connector cannot connect to QuickBooks Online:

  * Verify that the **Client ID** and **Client Secret** are correct.
  * Verify that the correct **Environment** is selected.
  * Confirm that the configured **Redirect URI** matches the URI registered in the Intuit developer application.
  * Click **Connect to QuickBooks** again and complete the OAuth authorization process.
  * Verify that the QuickBooks Online company is accessible using the authorized account.
  * Check the **Realm / Company ID** and **Token Status** in the configuration.
  * If the connection has expired or been revoked, reconnect the Magento store to QuickBooks.

==== Synchronization Not Processing ====

If synchronization operations remain pending:

  * Verify that **Magento Cron** is configured and running.
  * Verify that **Enable Cron Dispatch** is enabled.
  * Check the configured **Dispatch Interval**.
  * Check the **Max Operations Per Run** value.
  * Verify that the required entity dispatch options are enabled.
  * Review the synchronization logs for errors.
  * Check whether the synchronization queue contains pending or failed operations.

==== Customer or Product Import Issues ====

If customers or products are not being imported from QuickBooks:

  * Verify that the corresponding inbound import option is enabled.
  * Check the **Inbound Import Conflict Policy**.
  * Verify that the QuickBooks records contain the required information.
  * Review the synchronization logs for validation or mapping errors.
  * Confirm that the QuickBooks connection is active.

==== Magento to QuickBooks Export Issues ====

If Magento entities are not being exported:

  * Verify that the relevant entity export option is enabled.
  * Confirm that the entity meets the configured synchronization conditions.
  * For orders, verify the **Order Status Allowlist for Auto-Sync** when automatic order synchronization is enabled.
  * Check product, customer, tax, account, and payment mappings.
  * Review the synchronization logs for the failed operation.

==== Mapping Errors ====

If synchronization fails because of field, tax, or account mappings:

  * Verify that all mapping values use valid JSON where JSON configuration is required.
  * Verify that QuickBooks account IDs and tax code IDs are correct.
  * Check the configured **Customer Field Mappings**.
  * Check the configured **Product Field Mappings**.
  * Check the configured **Invoice Line Field Mappings**.
  * Review **Tax Class Mappings** and **Tax Rate Mappings**.
  * Correct the mapping configuration and retry the failed synchronization operation.

==== Failed Synchronization Operations ====

If an operation is marked as failed:

  - Open the synchronization logs in the Magento Admin Panel.
  - Identify the failed operation.
  - Review the error message and operation details.
  - Correct the underlying configuration or data issue.
  - Retry the failed operation.
  - Verify that the operation is processed successfully.

==== Automatic Synchronization Not Working ====

If automatic synchronization is not triggering:

  * Verify that the relevant **Auto-Sync** option is enabled.
  * Verify that Magento Cron is running.
  * Check the configured entity export settings.
  * For orders, verify that the order status is included in the configured allowlist.
  * Check the synchronization queue and logs.
  * Verify that the QuickBooks connection is active.

==== Cron and Queue Issues ====

If the synchronization queue is not being processed:

  * Confirm that Magento Cron is running correctly.
  * Verify that **Enable Cron Dispatch** is enabled.
  * Review the dispatch interval and maximum operations per run.
  * Check the Magento and QuickBooks Connector logs.
  * Verify that the server has sufficient resources to process queued operations.
  * Retry failed operations after resolving the underlying issue.

==== QuickBooks API or Authentication Errors ====

If QuickBooks returns an API or authentication error:

  * Verify that the QuickBooks connection is still active.
  * Reconnect the QuickBooks account if the OAuth token has expired or been revoked.
  * Verify that the selected QuickBooks environment matches the configured Intuit application.
  * Review the synchronization log for the exact QuickBooks API error.
  * Correct the related configuration or data and retry the operation.

==== Logs and Error Investigation ====

When troubleshooting an issue, always review the synchronization logs before making configuration changes.

The logs can help identify:

  * The affected Magento entity
  * The synchronization direction
  * The operation status
  * The error message
  * The synchronization attempt
  * The QuickBooks response

After resolving the issue, retry the failed operation and confirm that the synchronization completes successfully.

==== Recommended Troubleshooting Process ====

Use the following process when investigating a synchronization problem:

  - Check the QuickBooks connection status.
  - Verify Magento Cron is running.
  - Check the synchronization configuration.
  - Review the synchronization logs.
  - Identify the affected entity and operation.
  - Check mappings and required QuickBooks accounts or tax codes.
  - Correct the underlying issue.
  - Retry the failed operation.
  - Verify the result in both Magento and QuickBooks.

===== Related Magento 2 Docs =====

  * [[https://toweringmedia.com/installation|Magento 2 Extension Installation Guide]]
  * [[https://toweringmedia.com|Toweringmedia]]