Connect Gratona to QuickBooks Online

Authorize the correct QuickBooks Online company, configure one eligible program, then validate with a controlled first sync before you roll out additional programs. You can start from Integrations or Connected Apps.

For the object model and related topics, see the QuickBooks Online integration overview.

Before you start

You need an active QuickBooks Online company, permission to manage organization integration settings, and at least one Gratona program that has both a program form and a donor form. Only those programs appear for QuickBooks setup.

• Decide which QuickBooks Online company to authorize.

• Confirm the currencies you use in Gratona and QuickBooks. If they differ, see Synchronized Currency.

• Choose one program to configure and test first.

After you connect, Gratona maps:

• Donors to QuickBooks Customers

• Recipients to QuickBooks Service Items in Recipient items mode

• Donations to QuickBooks Sales Receipts

Connect from Integrations

Use Integrations when you want to authorize QuickBooks and open program setup from its card.

Open your account menu, then Organization settings > Integrations.

Find the QuickBooks card. Select Sign in to QuickBooks, or View Integration if it is already connected.

In the QuickBooks drawer, select Authorize QuickBooks, or Reauthorize QuickBooks when renewing access.

Choose the intended QuickBooks Online company and finish authorization.

Return to Gratona and reopen the QuickBooks drawer if needed. Choose a program under Select a Program.

Connect from Connected Apps

Open your account menu, then Organization settings > Connected apps.

Select Add provider, choose QuickBooks, and authorize the intended QuickBooks Online company.

When connected, select Manage on the QuickBooks card to configure programs, sync type and mappings. Confirm the connected company in the drawer before continuing. This drawer also contains Historical QuickBooks sync and Stripe payout reconciliation.

If QuickBooks shows Already added, open the existing connection instead of adding another. For connection health and reconnect actions, see Connected Apps.

If onboarding cannot start, read the displayed error and try again. You can also connect from the QuickBooks card under Organization settings > Integrations.

Choose a program and sync settings

After QuickBooks is connected, select one program and set sync direction and delete behavior before you map fields.

1. Open the QuickBooks drawer from Integrations, or open the QuickBooks connection from Connected Apps.

2. Under Select a Program, choose a program. If none appear, Connected Apps shows No eligible programs found. In the Integrations drawer, the program grid is empty instead. Add both a program form and a donor form to the program, then return here.

3. Set Sync Type to Gratona -> QBO, QBO -> Gratona, or Two way (default).

4. Leave Delete/deactivate linked QuickBooks records when deleted in Gratona off unless finance wants it. When on, customers and service items are made inactive in QuickBooks, and sales receipts are deleted.

5. Leave Delete linked Gratona records when deleted/deactivated in QuickBooks off unless finance wants it. When on, QuickBooks customer and item deactivation can delete linked Gratona donors and recipients, and QuickBooks sales receipt deletion can delete linked Gratona donations.

Both delete toggles default to off. Deletion sync is separate from disconnect. Turning a delete toggle on can remove linked donor, recipient, donation, or accounting records.

Map customer fields

Use the Customer tab to map donor fields to QuickBooks customer fields.

1. Open the Customer tab.

2. Under QuickBooks Field Mapping, match each donor field to a QuickBooks field.

3. Click Refresh fields if you need Gratona to query QuickBooks for the latest customer fields.

4. Leave Create separate donor records for matching emails off to update and link the existing donor when emails match. Turn it on only if you want a separate donor for the QuickBooks customer even when another donor already uses that email.

For how donor and customer records relate after setup, see Adding Donors (Customers).

Map service items

Recipient items is the default and uses the field mappings and category below. To reuse one item for program donations, choose Existing QuickBooks item; see Use an existing QuickBooks Service Item for a program.

1. Open the Service Item tab.

2. Under QuickBooks Program Field Mapping, map program fields to QuickBooks item fields.

3. Choose a Category.

4. Click Save Category.

For recipient and service item behavior after setup, see Recipients (Service item).

Configure donations

Use the Donations tab for sales receipt deposit settings in both modes. The default-item and designation-override steps below apply only to Recipient items mode. Existing QuickBooks item mode shows the selected program item and hides those legacy item controls.

1. Open the Donations tab.

2. Under Donations to Sales Receipts, set Sales Receipt Deposit Account (Optional) if sales receipts should deposit into a Bank or Other Current Asset account.

3. Under Donation Items by Campaign or Designation, set Default Item for Additional Gifts (Optional) if needed for standalone designation gifts. A recipient or campaign with an existing service item keeps that item.

4. Under Campaign and Designation Overrides, click Add to map specific designations to QuickBooks items.

5. Click Save Donation Settings for deposit account changes, and Save Item Settings if you changed additional gift items or designation overrides.

In Recipient items mode, recipient donations use their recipient service item. In Existing QuickBooks item mode, new program donations use the selected item ahead of recipient items, defaults and designation overrides. See Map donations, designations, accounts, and classes and Donations (Sales Receipt).

Configure accounting

Use the Accounting tab for program classes in both modes. Recipient items mode also includes an income-account setting for service items Gratona creates or updates.

1. Open the Accounting tab.

2. In Recipient items mode, under Service Item Accounting, set Service Item Income Account (Optional). This field is hidden in Existing QuickBooks item mode; the chosen item keeps its income account in QuickBooks.

3. When QuickBooks class tracking is enabled, set Service Item Class (Optional) in Recipient items mode, or Default Donation Class (Optional) under Donation Classes in Existing QuickBooks item mode. Both store the program’s default class.

4. For campaign programs with entity-specific class mapping, assign entity classes where needed. Entity classes override the program default; entities without a specific class still use the default class.

5. Click Save Attachment Settings.

What syncs after setup

Create and update traffic follows the program Sync Type. Historical QuickBooks sync is available from Connected Apps through a preview and approval workflow; selected records, eligibility, mappings and settings determine what can post.

Donors can create or update QuickBooks customers, and QuickBooks customers can create or update donors, depending on sync direction and customer field mapping. Existing links or matching identities may be reused.

In Recipient items mode, recipients and QuickBooks Service Items can create or update their linked records when direction and mappings resolve. In Existing QuickBooks item mode, recipient changes do not create, update or deactivate QuickBooks items, and inbound shared items do not create recipients.

An eligible positive donation can create a QuickBooks sales receipt after its payment is settled or otherwise qualifies as a completed gift. The customer and service item must resolve, currencies must match, and the program must allow outbound sync. Pending or failed payments do not post as completed gifts; refunds and disputes require separate review.

Inbound sales receipts require safe donor, program and item matches and an inbound-enabled Sync Type. Recipient items mode can create donations when recipient mappings resolve. A shared item does not identify a recipient: unfamiliar receipts using it need review, while updates to safely linked receipts preserve their Gratona designation. This does not automatically import every old QuickBooks receipt.

Verify the first sync

After you configure one program, validate with a known test donor and a small test donation before you configure additional programs. This is a manual operations check, not a product test mode.

1. Confirm you authorized the correct QuickBooks Online company.

2. Confirm Sync Type matches the direction your finance team wants.

3. Confirm both delete toggles are still off unless finance intentionally enabled them.

4. Create or use a known test donor and a small test donation for a mapped recipient or designation.

5. In QuickBooks, verify the Customer, Service Item, Sales Receipt amount, deposit account if you set one, and class if you set one.

6. Only then configure additional programs the same way.

Disconnect does not reverse accounting records already posted to QuickBooks. Review results with your finance team before expanding the rollout. Historical runs can provide a separate correction preview where supported; any correction needs its own review and approval. Deletion sync is separate and defaults off.

Reauthorize or disconnect

If authorization expires, Gratona displays an authorization-expired warning. Click Reauthorize QuickBooks and complete QuickBooks Online authorization again.

To remove the integration from the Integrations drawer:

1. Open the QuickBooks drawer.

2. Click Disconnect.

3. Confirm Disconnect QuickBooks. The saved QuickBooks authorization and program configuration are removed; reconnect and review setup before syncing again. This does not reverse records already created in QuickBooks.

In Connected Apps, Disconnect stops new sync work and keeps the connection in history. Remove is available after disconnection and retires its saved record matches. Neither action reverses accounting records already posted in QuickBooks. If sync fails after setup, see Troubleshoot QuickBooks synchronization.