> ## 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). For QuickBooks Online, contact Cedar support for alternative integration options.
</Info>

The integration works by:

1. Running on a schedule you configure in QuickBooks Web Connector
2. Fetching finalized invoices from Cedar ARMS
3. Creating or updating Sales Orders in QuickBooks Desktop
4. Tracking sync status to ensure data consistency

## 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

### New Invoices

When you finalize an invoice in Cedar ARMS:

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

### Updated Invoices

When 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 current charges

### Unfinalized Invoices

If an invoice is unfinalized after being synced:

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

## 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="Finalize Invoices">
    Only charges with **Invoiced** billing status are synced to QuickBooks.

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

    <Info>
      Charges in "Assigned" or other statuses will not appear in QuickBooks until the invoice is finalized.
    </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           |
| Invoice finalized             | —                 | Only "Invoiced" charges sync |

<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 invoice containing the charges is **finalized** (charges must be in "Invoiced" status)

    <Info>
      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 is **unfinalized** in Cedar after being synced. When an invoice no longer has charges in "Invoiced" status, the corresponding Sales Order is automatically deleted from QuickBooks.

    To restore: re-finalize the invoice in Cedar and it will sync 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)