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

# Configure Programs and Mappings

QuickBooks settings are stored per Gratona program. Open **Settings → Connected apps → QuickBooks Online**, select a program, and complete the settings that apply to it.

## Choose the sync direction

Use **Sync Type** to control supported ongoing changes:

| Setting           | Behavior                                                                                                   |
| ----------------- | ---------------------------------------------------------------------------------------------------------- |
| **Gratona → QBO** | Sends supported donors, recipients, and donations from Gratona to QuickBooks.                              |
| **QBO → Gratona** | Applies supported Customer, Item, and Sales Receipt changes received through verified QuickBooks webhooks. |
| **Two way**       | Enables both directions. This is the default.                                                              |

Changing the direction does not backfill older records. Use a [zero-write historical preview](/guides/advanced-features/integrations/quickbooks/financial-sync-and-recovery.md#sync-historical-records) for a controlled backfill.

## Choose deletion behavior

Deletion mirroring is off by default and has a separate control for each direction:

* **Delete/deactivate linked QuickBooks records when deleted in Gratona** makes linked Customers and Service Items inactive and deletes linked Sales Receipts.
* **Delete linked Gratona records when deleted/deactivated in QuickBooks** can delete linked donors or recipients after a Customer or Item is deactivated, and linked donations after a Sales Receipt is deleted.

Enable these controls only if QuickBooks and Gratona should share the same record lifecycle. Gratona uses the existing link between records and avoids sending the resulting change back as a duplicate action.

## Customer tab

Map donor form fields to QuickBooks Customer fields. Click **Refresh fields** after adding or changing Customer custom fields in QuickBooks.

For a new QuickBooks Customer whose email matches an existing donor, the default behavior is to update and link that donor. Enable **Create separate donor records for matching emails** only when matching emails should remain separate; use Gratona's Duplicates feature to review them later.

Stable linked identifiers take precedence over email matching. If an unlinked record has an ambiguous match, Gratona holds it for review instead of guessing.

## Service Item tab

Map recipient/program fields to QuickBooks Item fields. The recipient title field supplies the default Service Item name. You can also choose a QuickBooks item **Category** for Service Items created for the program.

Gratona keeps the stored QuickBooks Item link as the authoritative match. SKU is only a fallback for an unlinked item; an ambiguous or invalid mapping is held for review.

## Donations tab

Configure how donation Sales Receipts are posted:

* **Sales Receipt Deposit Account** is optional and accepts Bank or Other Current Asset accounts. If it is empty, QuickBooks applies its normal deposit handling.
* **Default Item for Additional Gifts** is the fallback QuickBooks Service Item for donations that are not recipient sponsorship income.
* **Designation Overrides** map a specific additional-gift designation to a different QuickBooks Service Item.

Recipient donations use the linked recipient Service Item. Additional gifts use the designation override first, then the default additional-gift item.

## Accounting tab

Choose the accounting context used by Service Items and Sales Receipts:

* **Service Item Income Account** lists Income and Other Income accounts. Select one before sending Service Items; Gratona does not choose an arbitrary account automatically.
* **Service Item Class** stores the program's default QuickBooks class.
* Campaign programs can enable **Add specific fund to a specific entity** to give individual recipients their own classes; recipients without an override use the program default.

QuickBooks class tracking must be enabled before QuickBooks accepts class references. If a saved account, class, or item is later removed or made inactive, Gratona holds affected records for correction rather than substituting an arbitrary value.

## Before enabling automatic sync

1. Confirm the connected QuickBooks company.
2. Select the intended sync direction.
3. Review both deletion controls.
4. Complete Customer and Service Item mappings.
5. Select the required accounting and donation mappings for the records you intend to send.
6. Create a small historical zero-write preview to verify the resulting actions before approving a wider backfill.