> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cedarai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# QuickBooks Web Connector

> Automatically sync Cedar ARMS invoices to QuickBooks Desktop

<img src="https://mintcdn.com/cedaraiinc/3XL8_nY45kQdoBAs/images/accounting-integrations/quickbooks-logo.svg?fit=max&auto=format&n=3XL8_nY45kQdoBAs&q=85&s=22baf221126b6dcc28c4de0f0f518d61" alt="QuickBooks Logo" style={{width: '200px'}} width="270" height="69" data-path="images/accounting-integrations/quickbooks-logo.svg" />

The QuickBooks Web Connector (QBWC) integration automatically syncs your Cedar ARMS invoices to QuickBooks Desktop as Sales Orders. This keeps your accounting records in sync without manual data entry.

## Overview

<Info>
  This integration requires **QuickBooks Desktop** (Pro, Premier, or Enterprise).⁠‌​​​​‌​​‌​​‌‌​​​‌‌​​​​‌​⁠ If you use the cloud product, see [QuickBooks Online setup](/user-docs/accounting-integrations/quickbooks-online).
</Info>

The integration works by:

1. Running on a schedule you configure in QuickBooks Web Connector
2. Fetching invoice charges that are eligible under your configured QBWC billing statuses
3. Creating or updating Sales Orders in QuickBooks Desktop
4. Tracking sync status to ensure data consistency

By default, only **Invoiced** charges are eligible, so they are fetched after invoice finalization. Cedar can also configure QBWC to include **Assigned** charges for synchronization before finalization.

## What is QuickBooks Web Connector?

QuickBooks Web Connector (QBWC) is a free application from Intuit that enables third-party applications like Cedar to exchange data with QuickBooks Desktop. It runs in the background on your Windows computer and periodically syncs data between Cedar and your QuickBooks company file.

<CardGroup cols={2}>
  <Card title="Official Setup Guide" icon="book-open" href="https://quickbooks.intuit.com/learn-support/en-us/help-article/install-products/set-quickbooks-web-connector/L4Vp7VI44_US_en_US">
    Intuit's official guide for installing and configuring QBWC
  </Card>

  <Card title="Download QBWC" icon="download" href="https://developer.intuit.com/app/developer/qbdesktop/docs/get-started/get-started-with-quickbooks-web-connector">
    Get the latest version from Intuit Developer
  </Card>

  <Card title="Troubleshooting Errors" icon="wrench" href="https://quickbooks.intuit.com/learn-support/en-us/help-article/open-programs/fix-common-web-connector-errors-quickbooks-desktop/L9slolvg0_US_en_US">
    Fix common QBWC error codes (QBWC1005, QBWC1006, etc.)
  </Card>

  <Card title="Programmer's Guide (PDF)" icon="file-pdf" href="https://static.developer.intuit.com/resources/QBWC_proguide.pdf">
    Detailed technical documentation from Intuit
  </Card>
</CardGroup>

## Prerequisites

Before setting up the integration, ensure you have:

* **QuickBooks Desktop** (Pro, Premier, or Enterprise) installed
* **QuickBooks Web Connector** installed — [download from Intuit](https://developer.intuit.com/app/developer/qbdesktop/docs/get-started/get-started-with-quickbooks-web-connector) and follow their [official setup guide](https://quickbooks.intuit.com/learn-support/en-us/help-article/install-products/set-quickbooks-web-connector/L4Vp7VI44_US_en_US)
* **Administrator access** to both QuickBooks and your Cedar account
* **Customers configured** in QuickBooks with names matching the GL numbers in Cedar
* **Service items configured** in QuickBooks matching your Cedar service types

<Tip>
  If you're new to QuickBooks Web Connector, we recommend reviewing Intuit's [official setup guide](https://quickbooks.intuit.com/learn-support/en-us/help-article/install-products/set-quickbooks-web-connector/L4Vp7VI44_US_en_US) first. It includes screenshots and detailed instructions for installing and configuring QBWC.
</Tip>

## Setup

<Steps>
  <Step title="Request QBWC credentials">
    Contact Cedar support to enable the QuickBooks Web Connector integration for your account. You'll receive:

    * A **QWC file** (QuickBooks Web Connector configuration file)
    * A **password** for authentication

    <Warning>
      Keep your QBWC password secure. It provides access to sync data between Cedar and QuickBooks.
    </Warning>
  </Step>

  <Step title="Add the application to QuickBooks Web Connector">
    1. Open QuickBooks Web Connector
    2. Click **Add an Application**
    3. Select the QWC file provided by Cedar
    4. When prompted, open your QuickBooks company file
    5. Authorize the Cedar application to access your QuickBooks data
  </Step>

  <Step title="Enter your password">
    In QuickBooks Web Connector:

    1. Find the Cedar application in the list
    2. Click in the **Password** column
    3. Enter the password provided by Cedar support
    4. Check the box to save the password
  </Step>

  <Step title="Test with manual syncs first">
    Before enabling automatic sync, run several manual syncs to verify the integration works correctly:

    1. Click **Update Selected** to run a manual sync
    2. Check that the sync completes without errors
    3. Verify Sales Orders appear in QuickBooks matching your Cedar invoices
    4. Review the data mapping (customers, service items, amounts)
    5. Run 2-3 more manual syncs to confirm consistency

    <Warning>
      If the sync behavior is not what you expect (wrong customers, missing items, incorrect amounts), **do not enable auto-sync**. Contact Cedar support at [support@cedarai.com](mailto:support@cedarai.com) to resolve any issues before proceeding.
    </Warning>
  </Step>

  <Step title="Enable automatic sync">
    Once you've verified the integration works correctly with manual syncs:

    1. Select the Cedar application
    2. Set the **Auto-Run** interval (e.g., every 30 minutes)
    3. Enable **Auto-Run**

    <Tip>
      We recommend syncing every 15-30 minutes during business hours to keep your accounting data current without overloading the system.
    </Tip>
  </Step>
</Steps>

## How Invoices Are Synced

### Invoice to Sales Order Mapping

Each Cedar invoice becomes a Sales Order in QuickBooks:

| Cedar Invoice Field | QuickBooks Sales Order Field |
| - | - |
| Invoice ID | Reference Number |
| Invoice date | Transaction Date |
| Customer GL Number | Customer |
| Charges | Line Items |

### Charge to Line Item Mapping

Each charge on an invoice becomes a line item:

| Cedar Charge Field | QuickBooks Line Item Field |
| - | - |
| Service Type | Item |
| Description (with equipment info) | Description |
| Rate | Rate |
| Calculated quantity | Quantity |
| Amount | Amount |

<Info>
  The line item description includes the railcar number (e.g., "BNSF 123456 | Storage | Railcar Storage") to help you identify specific equipment on the invoice.
</Info>

## Sync Behavior

The examples below distinguish the default **Invoiced-only** policy from a connection configured to include **Assigned** charges.

### New Invoices Under the Default Policy

Under the default Invoiced-only policy, finalizing an invoice makes its charges eligible:

1. The next QBWC sync picks up the new invoice
2. A new Sales Order is created in QuickBooks
3. The sync status is tracked to prevent duplicates

When Assigned is enabled, eligible Assigned charges can synchronize before invoice finalization. QBWC creates or updates the Desktop Sales Order using the charges whose statuses are currently enabled.

### Updated Invoices

When eligible charges are added or removed from an existing invoice:

1. The QBWC sync detects the change
2. The existing Sales Order in QuickBooks is updated
3. Line items are replaced with the charges that remain eligible under the configured billing statuses

### Unfinalized Invoices Under the Default Policy

Under the default Invoiced-only policy, unfinalizing a synced invoice makes its charges ineligible:

1. The QBWC sync detects that the invoice no longer has eligible charges
2. The Sales Order is deleted from QuickBooks
3. You can re-finalize and synchronize it again when ready

When Assigned is enabled, unfinalization does not necessarily delete the Desktop Sales Order. The Sales Order remains and is updated as long as at least one charge remains eligible under the configured billing statuses. QBWC deletes it only after no eligible charges remain.

## Configuration Checklist

Before syncing, ensure the following items are configured correctly in both Cedar and QuickBooks.⁠‌​​​​‌​​‌​​‌‌​​​‌‌​​​​‌​⁠ Most sync errors can be resolved by checking these settings.

### Cedar Configuration

<Steps>
  <Step title="Set up General Ledger (GL) Numbers">
    Each **Customer Location** in Cedar must have a **GL Number** configured. This GL number is used to match the customer in QuickBooks.

    **In Cedar ARMS:**

    1. Go to the Customer Location settings
    2. Find the **General Ledger Number** field
    3. Enter a value that matches the customer name in QuickBooks (or note it to create a matching customer in QuickBooks)

    <Warning>
      Charges without a GL number on their customer location will **not sync** to QuickBooks. They are intentionally skipped to prevent errors.
    </Warning>
  </Step>

  <Step title="Configure Service Types">
    Each **Service Type** used on charges must match a **Service Item** name in QuickBooks exactly.

    You can either:

    * Update service types in Cedar to match existing QuickBooks items, OR
    * Create new service items in QuickBooks to match Cedar's service types

    **Common service types include:**

    * Storage
    * Switching
    * Demurrage
    * Handling
  </Step>

  <Step title="Verify Rate Configuration">
    For accurate rate and quantity display in QuickBooks:

    * Charges with rate information will show the **rate** and **calculated quantity**
    * Charges without rate information will show the **total amount** as the rate with **quantity = 1**

    <Tip>
      To ensure rates sync correctly, configure your rates in Cedar's rate management. The rate is extracted from the charge's rate information.
    </Tip>
  </Step>

  <Step title="Confirm the Billing Status Policy">
    The default QBWC policy synchronizes only **Invoiced** charges. Under that policy:

    1. Create charges in ARMS
    2. Assign charges to an invoice
    3. Finalize the invoice to set charges to "Invoiced" status

    <Info>
      Cedar can configure QBWC to include **Assigned** charges when your accounting workflow needs an earlier sync. With
      that configuration, Assigned charges can appear in QuickBooks before invoice finalization. Ask your Cedar
      administrator which statuses are enabled for your connection.
    </Info>
  </Step>
</Steps>

### QuickBooks Configuration

<Info>
  If you already have customers and service items in QuickBooks, you can skip creating new ones and instead update the GL numbers and service types in Cedar to match your existing QuickBooks data.
</Info>

<Steps>
  <Step title="Match or Create Customers">
    Each GL number in Cedar must correspond to a **Customer** in QuickBooks. You can either:

    **Option A: Update Cedar to match QuickBooks**

    * Set the GL number in Cedar to match an existing QuickBooks customer name

    **Option B: Create customers in QuickBooks to match Cedar**

    1. Go to **Customers** → **Customer Center**
    2. Click **New Customer & Job** → **New Customer**
    3. Enter the **Customer Name** exactly matching the GL number in Cedar

    | Cedar GL Number | QuickBooks Customer Name |
    | - | - |
    | `ACME-001` | `ACME-001` |
    | `Customer ABC` | `Customer ABC` |

    <Warning>
      Names must match **exactly**, including capitalization and special characters.
    </Warning>
  </Step>

  <Step title="Match or Create Service Items">
    Each service type in Cedar must correspond to a **Service Item** in QuickBooks. You can either:

    **Option A: Update Cedar to match QuickBooks**

    * Change your service types in Cedar to match existing QuickBooks service item names

    **Option B: Create service items in QuickBooks to match Cedar**

    1. Go to **Lists** → **Item List**
    2. Click **Item** → **New**
    3. Select **Service** as the item type
    4. Enter the **Item Name** exactly matching the Cedar service type

    | Cedar Service Type | QuickBooks Service Item |
    | - | - |
    | `Storage` | `Storage` |
    | `Switching` | `Switching` |
    | `Demurrage` | `Demurrage` |
  </Step>

  <Step title="Verify Active Status">
    Ensure customers and service items are **Active** in QuickBooks. Inactive items will cause sync errors.
  </Step>
</Steps>

### Quick Reference: What Must Match

The GL numbers and service types in Cedar must match the customer names and service items in QuickBooks. **You can update either system** to make them match — whichever is easier for your workflow.

| Cedar Field | QuickBooks Field | Notes |
| - | - | - |
| Customer Location → GL Number | Customer Name | Must match exactly |
| Charge → Service Type | Service Item Name | Must match exactly |
| Charge billing status | — | Invoiced by default; Assigned can be enabled |

<Tip>
  **Already have customers and items in QuickBooks?** Instead of creating new ones, you can update the GL numbers and service types in Cedar to match your existing QuickBooks data.
</Tip>

## Troubleshooting

<Note>
  For QBWC-specific error codes (QBWC1005, QBWC1006, QBWC1007, etc.), see Intuit's official guide: [Fix common Web Connector errors](https://quickbooks.intuit.com/learn-support/en-us/help-article/open-programs/fix-common-web-connector-errors-quickbooks-desktop/L9slolvg0_US_en_US)
</Note>

<AccordionGroup>
  <Accordion title="Sync fails with authentication error">
    * Verify your password is entered correctly in QBWC
    * Ensure the password hasn't expired (contact Cedar support if needed)
    * Check that QuickBooks is open and logged in during sync
  </Accordion>

  <Accordion title="Some charges are not syncing">
    Charges require a **General Ledger (GL) Number** on the customer location to sync. Check that:

    1. The customer location in Cedar has a GL number configured
    2. The GL number matches a customer name in QuickBooks
    3. The charge has a billing status enabled for your QBWC connection

    <Info>
      The default policy requires Invoiced charges. Assigned charges are eligible only when Cedar has configured that
      status for your connection. Charges without a GL number are intentionally skipped to prevent errors in QuickBooks.
    </Info>
  </Accordion>

  <Accordion title="Customer not found error">
    The customer name in QuickBooks must exactly match the GL number configured in Cedar. To fix:

    1. Check the GL number on the customer location in Cedar
    2. Ensure a customer with that exact name exists in QuickBooks
    3. Create the customer in QuickBooks if missing
    4. Verify the customer is **Active** (not inactive)
  </Accordion>

  <Accordion title="Service item not found error">
    Each service type in Cedar must have a matching Service Item in QuickBooks. To fix:

    1. Check which service types are on the failing invoice in Cedar
    2. Create matching Service Items in QuickBooks (**Lists** → **Item List** → **New** → **Service**)
    3. Ensure the names match exactly (case-sensitive)
    4. Verify the item is **Active**
  </Accordion>

  <Accordion title="Rate or quantity appears incorrect">
    The integration extracts rate information from the charge's rate configuration:

    * If rate info exists: displays the **rate** and **calculated quantity** (amount ÷ rate)
    * If no rate info: displays the **total amount** as rate with **quantity = 1**

    To fix, ensure your rates are properly configured in Cedar's rate management.
  </Accordion>

  <Accordion title="Sales Order already exists">
    This can happen if a sync was interrupted. The next sync will automatically update the existing Sales Order instead of creating a duplicate.
  </Accordion>

  <Accordion title="Sync is stuck or not progressing">
    If invoices are stuck in a pending state:

    1. Close and reopen QuickBooks Web Connector
    2. Click **Update Selected** to force a manual sync
    3. Contact Cedar support if the issue persists
  </Accordion>

  <Accordion title="Invoice synced but then deleted from QuickBooks">
    This happens when an invoice no longer has charges eligible under your configured QBWC billing-status policy. Under
    the default Invoiced-only policy, unfinalizing an invoice makes its charges ineligible and the corresponding Sales
    Order is automatically deleted from QuickBooks.

    To restore it under the default policy, re-finalize the invoice in Cedar. It will synchronize again on the next run.
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Keep QuickBooks open" icon="desktop">
    QBWC requires QuickBooks to be open and logged in during sync.⁠‌​​​​‌​​‌​​‌‌​​​‌‌​​​​‌​⁠ Consider running it on a dedicated workstation.
  </Card>

  <Card title="Sync during business hours" icon="clock">
    Schedule syncs during times when QuickBooks is actively used to ensure the company file is open.
  </Card>

  <Card title="Review sync logs" icon="list-check">
    Periodically check QBWC logs for errors and address customer/item mapping issues promptly.
  </Card>

  <Card title="Configure GL numbers" icon="hashtag">
    Ensure all customer locations have GL numbers configured before finalizing invoices.
  </Card>
</CardGroup>

## Getting Help

If you encounter issues not covered here:

* Check the QuickBooks Web Connector log for detailed error messages
* Review [Intuit's official troubleshooting guide](https://quickbooks.intuit.com/learn-support/en-us/help-article/open-programs/fix-common-web-connector-errors-quickbooks-desktop/L9slolvg0_US_en_US) for QBWC-specific errors
* Contact Cedar support at [support@cedarai.com](mailto:support@cedarai.com) for Cedar-specific issues

## Related Pages

* [Accounting Integrations Overview](/user-docs/accounting-integrations/overview)
* [QuickBooks Online Setup](/user-docs/accounting-integrations/quickbooks-online)


## Related topics

- [QuickBooks Online](/user-docs/accounting-integrations/quickbooks-online.md)
- [Accounting Integrations](/user-docs/accounting-integrations/overview.md)
- [Introduction](/user-docs/index.md)
- [Workflow Effect Webhooks](/user-docs/arms/webhooks/overview.md)
- [MCP privacy addendum](/user-docs/api-reference/mcp-privacy.md)