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

# QuickBooks

> Push invoices and payments from Nyumba Zetu into QuickBooks Online, and track what has and has not synced.

**Finance → Accounting → Quickbooks → `/quickbooks/invoices`** · Payments → `/quickbooks/payments`

Organisations that keep their statutory books in **QuickBooks Online** do not have to re-key
anything: the QuickBooks screens list the invoices and payments Nyumba Zetu has raised, in the shape
QuickBooks expects, and push the ones you select.

<Note>
  QuickBooks is enabled per branch rather than self-serve. The menu entry and both grids only appear
  for branches on the QuickBooks subscriber list — ask support to enable it for yours. Everything
  below assumes it is already connected.
</Note>

## What syncs, and in which direction

The sync is **one-way: Nyumba Zetu → QuickBooks**.

| Object here                                            | Becomes in QuickBooks                            |
| ------------------------------------------------------ | ------------------------------------------------ |
| Invoice (with its line items, tax code and tax amount) | Invoice                                          |
| Payment                                                | Payment, applied against the matching invoice    |
| Lease / resident being billed                          | Customer, created on demand if it does not exist |

Nyumba Zetu stays the system of record for money. QuickBooks holds the accounting mirror, and the
platform keeps a crosswalk of every pushed object — the QuickBooks id plus its sync token — so a
re-sync updates the existing QuickBooks record instead of creating a duplicate.

<Warning>
  Do not create the same invoice by hand in QuickBooks *and* sync it from here. The crosswalk only
  knows about records the platform pushed; a hand-made copy becomes a second invoice against the same
  customer, and the two will not reconcile.
</Warning>

## The Invoices tab

The grid deliberately mirrors QuickBooks' own invoice import layout, which is why several column
headers carry an asterisk — those are the fields QuickBooks treats as required:

| Column                                                                | Notes                                                                                          |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **\*InvoiceNo**                                                       | The Nyumba Zetu invoice number. It becomes the QuickBooks document number.                     |
| **\*Customer**                                                        | The QuickBooks customer name resolved for the lease.                                           |
| **\*InvoiceDate** / **\*DueDate**                                     | Straight from the invoice.                                                                     |
| **Item(Product/Service)**                                             | The service type behind the line, mapped to a QuickBooks item.                                 |
| **ItemDescription**, **ItemQuantity**, **ItemRate**, **\*ItemAmount** | The line detail.                                                                               |
| **\*ItemTaxCode**, **ItemTaxAmount**                                  | The tax class and computed tax. Tax is exclusive — see [Tax and eTIMS](/guides/tax-and-etims). |
| **Synced**                                                            | `True` in green once the invoice exists in QuickBooks, `False` in red while it does not.       |

Because the layout matches the import template, exporting the grid gives you a file you can load
into QuickBooks manually if you ever need to work offline. See [Reports](/guides/reports) for export
mechanics.

## The Payments tab

The same treatment for receipts: each row is a payment recorded here, with its own **Synced**
flag. Sync payments *after* their invoices — a payment cannot be applied in QuickBooks until the
invoice it settles is there.

## Syncing

<Steps>
  <Step title="Filter to what has not synced">
    Sort or filter on **Synced = False**. That is the backlog; everything else is already in
    QuickBooks.
  </Step>

  <Step title="Select the rows">
    Tick the invoices or payments you want to push. Selection is per grid — invoices and payments
    are pushed separately.
  </Step>

  <Step title="Run “Sync with QuickBooks”">
    The bulk action asks for confirmation, then pushes each selected row and marks it synced.
  </Step>

  <Step title="Re-read the Synced column">
    Refresh the grid. Anything still `False` did not go through — see below.
  </Step>
</Steps>

## When a row will not sync

| Symptom                                | Usual cause                                                                                                                              |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Everything fails at once               | The QuickBooks connection has expired or been revoked. It has to be re-authorised.                                                       |
| One invoice fails                      | A required field is empty — most often the customer, the service type's item mapping, or the tax code. Fix the invoice, then sync again. |
| A payment fails but its invoice synced | The payment is applied to an invoice that is not in QuickBooks yet, or is applied across more than one invoice. Sync the invoices first. |
| A row flips back to `False`            | The QuickBooks record was deleted on the QuickBooks side. Sync again to recreate it.                                                     |

Re-running the sync on an already-synced row is safe: the crosswalk makes it an update, not a
duplicate.

## Good practice

* **Sync on a rhythm** — end of day or end of week — rather than ad hoc. A predictable backlog is
  easier to read than a grid where nobody knows what was last pushed.
* **Reconcile monthly.** Compare the [financial statements](/guides/financial-statements) here
  against the equivalent QuickBooks report before you close the period. They should agree to the
  cent; a gap means something failed to sync and nobody looked.
* **Fix data here, not there.** Correcting the invoice in Nyumba Zetu and re-syncing keeps both
  sides consistent. Editing the copy in QuickBooks leaves the platform believing the wrong figure
  is filed.
* **Do not use QuickBooks as the arrears source.** Balances, allocations and collections all read
  the platform ledger — see [Invoices and payments](/guides/invoices-and-payments).