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

> Connect QuickBooks Online and synchronize finalized Cedar ARMS invoices

QuickBooks Online synchronization sends finalized Cedar ARMS invoices to one QuickBooks Online company. It runs in the background, reports progress in ARMS, and retries temporary failures automatically.

<Warning>
  QuickBooks Online is available only to approved pilot and limited-availability accounts. Contact your Cedar
  administrator to request access. This setup guide does not mean the integration is enabled for your account.
</Warning>

<Info>
  QuickBooks Online creates **posting Invoices in accounts receivable**. This differs from the QuickBooks Desktop
  integration, which creates non-posting Sales Orders.
</Info>

## Before You Connect

You need:

* Permission to view and update invoices in Cedar ARMS
* An Intuit user who can authorize applications for the QuickBooks Online company
* Active Customers and Items in QuickBooks Online for the customer locations and service types you invoice

<Warning>
  Synchronization is future-only. ARMS does not enroll invoices first finalized before the connection was confirmed or
  while the integration was disconnected. Reconnecting does not scan or backfill those invoices.
</Warning>

If **QuickBooks Online** does not appear under Invoice settings, the integration has not been enabled for your account.

## Connect a Company

<Steps>
  <Step title="Open QuickBooks Online settings">
    In Cedar ARMS, go to **Settings → Invoice settings → QuickBooks Online**.
  </Step>

  <Step title="Authorize Cedar">
    Select **Connect QuickBooks Online**, sign in to Intuit, and choose the company that should receive finalized ARMS invoices.

    Intuit returns you to ARMS after authorization.
  </Step>

  <Step title="Confirm the company">
    Review the company name before selecting **Connect company**.

    You can cancel without changing the existing connection. Canceling revokes the pending authorization and removes
    its stored credential. Start **Connect QuickBooks Online** again when you are ready.
  </Step>

  <Step title="Configure mappings">
    Map every customer location and service type used by your invoices. An invoice cannot synchronize until all required mappings are valid.
  </Step>
</Steps>

## Configure Mappings

ARMS uses explicit mappings instead of matching names automatically.

### Customer location mappings

For each Cedar customer location, search for and select the active QuickBooks Online **Customer** that should receive its invoices.

All charges on one ARMS invoice must resolve to the same QuickBooks Online Customer. If they map to different Customers, the invoice needs attention.

### Service type mappings

For each Cedar service type, search for and select the active QuickBooks Online **Item** used for that charge.

<Tip>
  After you correct a missing Customer or Item mapping, ARMS automatically requeues affected invoices. You do not need
  to finalize them again.
</Tip>

## What Gets Synchronized

| Cedar ARMS                          | QuickBooks Online                                            |
| ----------------------------------- | ------------------------------------------------------------ |
| Finalized invoice                   | Posting Invoice                                              |
| Invoice ID                          | Document number                                              |
| First invoiced charge date          | Transaction date                                             |
| Mapped customer location            | Customer                                                     |
| Mapped service type                 | Item                                                         |
| Charge description                  | Line description, including equipment details when available |
| Charge rate and calculated quantity | Unit price and quantity                                      |
| Charge amount                       | Line amount                                                  |

Only finalized invoices with invoiced charges are eligible. A new eligible invoice is normally queued immediately, and synchronization usually begins within one minute.

## Choose an Unfinalize Policy

The policy controls what happens in QuickBooks Online after a synchronized ARMS invoice is unfinalized and then finalized again. It does not change ARMS invoice history.

<Tabs>
  <Tab title="Update in place">
    ARMS keeps the existing QuickBooks Online Invoice while the ARMS invoice is unfinalized. When you finalize it again, ARMS updates that same QuickBooks Online Invoice and keeps its QuickBooks Online ID.
  </Tab>

  <Tab title="Void and replace">
    ARMS voids the existing QuickBooks Online Invoice. If the ARMS invoice is finalized again, ARMS waits for the void to succeed before creating a replacement with a new QuickBooks Online ID.
  </Tab>
</Tabs>

Change the policy under **When a finalized invoice is unfinalized** on the QuickBooks Online settings page.

For an invoice generation that ARMS already tracks, unfinalization and re-finalization intent is preserved while
synchronization is paused or the company is disconnected. ARMS resumes that proven work only after the eligible
connection is safely restored. This does not enroll or backfill invoices first finalized during the disconnected period.

## Monitor Synchronization

The settings page shows queued, synchronizing, action-required, and recently successful invoices. A synchronized invoice also shows a link to the matching QuickBooks Online Invoice from its ARMS invoice details.

Temporary Intuit, network, and throttling failures move to **Retrying**. ARMS retries them automatically with increasing delays and duplicate-safe request identifiers. If automatic retries are exhausted, the invoice moves to **Action required**.

Common action-required conditions include:

* A Customer or Item mapping is missing or no longer active
* Charges on one invoice map to more than one QuickBooks Online Customer
* The invoice no longer contains eligible invoiced charges
* Intuit authorization was revoked or expired
* QuickBooks Online rejected the invoice data

When authorization must be renewed, select **Reconnect QuickBooks Online**, authorize the company, and confirm it again.
Reauthorizing the same company keeps its mappings and resumes eligible work already proven for that company. Connecting
a different company requires new mappings and never replays work that belongs to the old company.

## Disconnect

Select **Disconnect**, review the company name, and confirm.

Disconnecting:

* Stops new invoices from being queued
* Revokes Cedar's authorization and removes its stored refresh credential
* Does not delete or void existing QuickBooks Online Invoices
* Does not backfill the disconnected interval after a later reconnect

You can reconnect from the same settings page. Only invoices finalized after the new connection is confirmed are eligible.

## Security

Cedar requests only the QuickBooks Online accounting permission needed for this integration. Access and refresh tokens are never returned in browser payloads. Cedar stores refresh credentials in its managed secret store and rotates them when Intuit issues a replacement.

Connection attempts expire, can be used only once, and are bound to the Cedar user and carrier that started them.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The QuickBooks Online page is missing">
    The integration must be enabled for your account, and your Cedar role must allow you to view and update invoices.
  </Accordion>

  <Accordion title="The connection request expired">
    Return to QuickBooks Online settings and start a new connection. An expired or already-used request cannot be
    confirmed.
  </Accordion>

  <Accordion title="An invoice needs a mapping">
    Open the Customer location mappings and Service type mappings sections. Select active QuickBooks Online records for
    every source listed on the invoice. Saving the missing mapping automatically requeues matching invoices.
  </Accordion>

  <Accordion title="The connection requires reauthorization">
    Select **Reconnect QuickBooks Online**, sign in to Intuit, select the intended company, and confirm it in ARMS.
  </Accordion>

  <Accordion title="An older invoice did not synchronize">
    ARMS synchronizes only invoices finalized after the current connection was confirmed. It does not backfill invoices
    finalized before connection or during a disconnected interval.
  </Accordion>
</AccordionGroup>

## Related Pages

* [Accounting Integrations Overview](/user-docs/accounting-integrations/overview)
* [QuickBooks Web Connector for QuickBooks Desktop](/user-docs/accounting-integrations/quickbooks-web-connector)