> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/erp-and-accounting-integrations/quickbooks.md).

# QuickBooks Online

## Synchronisation scope

| Synchronisation                              | Direction            | When it runs                                                                |
| -------------------------------------------- | -------------------- | --------------------------------------------------------------------------- |
| Invoices and credit notes                    | Younium → QuickBooks | When an invoice is posted in Younium, with invoice posting on               |
| Journals                                     | Younium → QuickBooks | On demand, when a posted journal is sent to QuickBooks                      |
| Invoice payment status                       | QuickBooks → Younium | As a scheduled job; invoices fully paid in QuickBooks are marked as settled |
| Accounts                                     | QuickBooks → Younium | On demand from the integration settings, or as a scheduled job              |
| Accounts                                     | Younium → QuickBooks | On demand from the integration settings, or as a scheduled job              |
| Products                                     | QuickBooks → Younium | On demand from the integration settings, or as a scheduled job              |
| Currencies, exchange rates and payment terms | QuickBooks → Younium | On demand from the integration settings, or as a scheduled job              |
| Chart of accounts and tax codes              | QuickBooks → Younium | On demand from the integration settings                                     |

***

## Overview

The QuickBooks Online integration posts Younium invoices and credit memos to QuickBooks when an invoice is posted. Younium connects with Intuit OAuth 2.0. Posted documents take QuickBooks' automatic document numbers, and the number QuickBooks returns is stored against the Younium invoice so the two can be reconciled.

***

## Authentication

You connect Younium to QuickBooks Online by authorising it through Intuit. Enter the client id and secret of your Intuit app in the integration settings, choose whether to connect to a sandbox or a production company, then complete the sign-in at Intuit and approve the access Younium asks for. Intuit returns you to the integration settings page in Younium whether or not the authorisation succeeded — if it failed, the connection simply does not show as live and you can retry from there.

The settings page always opens, whether or not QuickBooks has been connected yet: a legal entity that has never connected sees the setup form ready to fill in, rather than an error.

The connection has to be valid before Younium will post anything; until it is, posting an invoice in Younium creates nothing in QuickBooks. Younium renews its own access from then on, so the connection stays live without intervention.

***

## Activation and deactivation

Activating validates the client credentials and completes the connection at Intuit. Each authorisation attempt is single-use: completing the same authorisation link a second time, or returning to Intuit on a stale or bookmarked link, fails and the connection must be started again from Younium.

Saving the settings turns invoice posting on or off to match your choice. Deactivating clears the settings and stops invoice posting; documents already in QuickBooks are untouched.

***

## Custom fields

| Entity                           | Custom field name            | Notes                                       |
| -------------------------------- | ---------------------------- | ------------------------------------------- |
| OrderProductCharge (and related) | `Quickbooks Online Tax Code` | List; Key used as QBO `TaxCodeRef` when set |

***

## Eligibility and filtering

* The QuickBooks connection is valid.
* Lines: `HideZeroAmountRecurring`, `HideZeroAmountUsageAndMeasurementLines`.
* Credit when `Invoice.Subtotal.Amount < 0` → `CreditMemo`; else `Invoice`.
* Every line must resolve `ExternalERPId` on order product charge, else charge; otherwise error.
* Invoice and delivery address **Country.Name** required.
* Invoice fee lines are sent alongside product lines. A fee line takes its item from the fee template's **External ERP id**, and posting fails with an error naming the template when it is empty. See [Invoice fees](https://docs.younium.com/platform/billing.md#invoice-fees).

***

## Field mapping — posted invoice (Younium → QuickBooks)

### Header (`Invoice` / `CreditMemo`)

| Younium field                                  | QuickBooks field               |
| ---------------------------------------------- | ------------------------------ |
| —                                              | `AutoDocNumber` = true         |
| `Invoice.InvoiceDate`                          | `TxnDate`                      |
| `Invoice.DueDate`                              | `DueDate`                      |
| `Account.InvoiceEmailAddress`                  | `BillEmail.Address`            |
| `PaymentTermReference.Description` / `.Name`   | `SalesTermRef.name` / `.Value` |
| `Invoice.Notes`                                | `CustomerMemo.Value`           |
| `Account.Name` / `ExternalERPId`               | `CustomerRef.name` / `.Value`  |
| `Invoice.InvoiceAddress.*`                     | `BillAddr` (see below)         |
| `Invoice.DeliveryAddress.*` or invoice address | `ShipAddr`                     |

When `MapAddressNameOnInvoice` is true, name is mapped to `Line1` and street fields shift to `Line2`/`Line3`.

### Line (`SalesItemLineDetail`)

| Younium field                                                            | QuickBooks field                             |
| ------------------------------------------------------------------------ | -------------------------------------------- |
| Charge name, service period (user culture date format), notes, qty + UoM | `Description`                                |
| Signed `Subtotal.Amount`                                                 | `Amount`                                     |
| `ProductName` / external ERP id                                          | `ItemRef.name` / `.Value`                    |
| OPC custom tax list Key or default                                       | `TaxCodeRef` (`TAX` when no OPC tax code)    |
| Line subtotal (signed on credit)                                         | `UnitPrice` via `AnyIntuitObject`, `Qty` = 1 |

### Write-back (Younium)

| QuickBooks field | Younium field           |
| ---------------- | ----------------------- |
| `DocNumber`      | `Invoice.ExternalERPId` |

***

## Post invoice workflow

**Runs when:** an invoice is posted in Younium.

Requests are rate-limited to stay within QuickBooks' API limits.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.younium.com/erp-and-accounting-integrations/quickbooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
