Troubleshoot QuickBooks synchronization

Start with authorization, program eligibility, Sync Type and the selected Service Item mode. Recipient items is the default; Existing QuickBooks item reuses one item for new program donations. For that setup and its checks, see Use an existing QuickBooks Service Item for a program.

Looking for historical runs under Select a Program? The older Integrations QuickBooks drawer does not contain them. Historical QuickBooks sync lives in Organization settings > Connected apps: open the QuickBooks Online card, click Manage, and scroll to Historical QuickBooks sync. See Run a historical QuickBooks sync.

For connection setup, see Connect Gratona to QuickBooks Online. For deposit accounts, designations, and classes, see Map donations, designations, accounts, and classes. For the object model, see QuickBooks Online integration overview.

Common first checks

Confirm the connection is authorized, the program is eligible, and the program Sync Type allows the direction you expect before investigating a single donation.

• Open the QuickBooks drawer from Integrations or the QuickBooks connection from Connected Apps.

• If you see QuickBooks authorization expired. Please re-authorize your QuickBooks connection., reauthorize before changing mappings.

• Under Select a Program, confirm the program appears and Sync Type is Gratona -> QBO or Two way when donations should create sales receipts in QuickBooks.

• Confirm Customer mappings and the program’s Service Item mode. Recipient items uses recipient field mappings, category and income-account settings. Existing QuickBooks item requires a selected active Service Item with an income account in QuickBooks. Check deposit and class settings on Donations and Accounting in either mode.

Symptom: Gratona shows QuickBooks authorization expired. Please re-authorize your QuickBooks connection., or sync stops after a period of working.

Cause: The QuickBooks Online authorization is no longer valid.

Fix:

1. Open your account menu, then Organization settings > Integrations, and open the QuickBooks drawer.

2. Click Reauthorize QuickBooks.

3. Confirm you are reconnecting the intended QuickBooks Online company, then finish authorization.

4. If you manage connection health in Connected Apps, use reconnect there after checking the provider status.

Symptom: No programs are available under Select a Program. Connected Apps shows No eligible programs found.; the Integrations drawer shows an empty program grid.

Cause: Only programs with both a program form and a donor form appear for QuickBooks setup.

Fix:

1. Attach both a program form and a donor form to the program.

2. Return to the QuickBooks drawer and open Select a Program again.

Symptom: You opened the QuickBooks drawer from Integrations, see Select a Program, and cannot find any historical run history.

Cause: The Integrations QuickBooks drawer contains program setup, while historical sync and run history are in the QuickBooks Manage drawer under Organization settings > Connected apps. If a program is open there, select Programs to return to the connection overview.

Fix:

1. Open your account menu and choose Organization settings > Connected apps.

2. Open the QuickBooks Online card and click Manage.

3. Scroll to Historical QuickBooks sync and use Refresh history under Recent historical runs.

If you approved a historical plan and no execution run appears after refreshing, contact support. See Run a historical QuickBooks sync.

Symptom: A customer field that exists in QuickBooks does not appear under QuickBooks Field Mapping, or the donor form shows No donor fields are available to map for this donor form.

Cause: Gratona is using a cached QuickBooks field list, the wrong company is connected, or the donor form has no mappable fields.

Fix:

1. Open the Customer tab.

2. Click Refresh fields to query QuickBooks for new customer fields.

3. If refresh fails, confirm the correct QuickBooks company is connected, that the company has at least one customer, then Reauthorize QuickBooks.

4. Contact support if the fields still do not appear.

Symptom: A QuickBooks customer with the same email as an existing Gratona donor either updates the existing donor or creates a second donor unexpectedly.

Cause: The Create separate donor records for matching emails setting controls this path. By default it is off, so Gratona links and updates the existing donor instead of creating another record.

Fix:

1. Open the Customer tab for the program.

2. Leave Create separate donor records for matching emails unchecked to keep linking existing donors.

3. Turn the setting on only if your organization intentionally needs separate donors that share an email address.

4. Use your normal donor duplicate tools if you need to merge records later.

Symptom: A new donation in Gratona does not appear as a QuickBooks sales receipt.

Cause: Common product-backed reasons include:

• The donation is non-positive or its payment was unsuccessful, so it is skipped. Pending payments wait for settlement. Refunded or disputed gifts are held for separate review.

• No QuickBooks customer or service item resolves for the donation.

• Sync Type is QBO -> Gratona, so Gratona does not push donations to QuickBooks.

• Authorization is expired.

• The donation existed before the integration was connected, so it is not synced automatically.

Fix:

1. Confirm the donation amount is positive and its payment is settled or otherwise qualifies as a completed gift. Refunded and non-positive donations do not create ordinary sales receipts. A successful refund can create a separate QuickBooks RefundReceipt when the original sales receipt is linked and available; it does not rewrite the original. Check sync history before assuming the refund adjustment posted.

2. Confirm the donor links to a valid QuickBooks Customer, or its email matches exactly one Customer. For new donations, Existing QuickBooks item uses the selected program item ahead of recipient items, defaults and overrides. In Recipient items mode, check the recipient item or applicable additional-gift default or designation override; the general default does not repair a missing recipient item. Also confirm currency alignment; see Synchronized Currency.

3. Set Sync Type to Gratona -> QBO or Two way when donations should create sales receipts.

4. Reauthorize if the connection expired.

5. Create a new test donation after connect to confirm mappings. To bring in older donations, run a manual historical sync; see Run a historical QuickBooks sync.

See Map donations, designations, accounts, and classes and Donations (Sales Receipt).

Symptom: A Stripe payout or bank deposit total does not match an individual QuickBooks sales receipt, often because of batching or processing fees.

Cause: Sales receipts are donation-level records, so a Stripe payout total that batches fees and multiple gifts does not match one sales receipt.

Fix:

1. Treat each sales receipt as a donation-level record, not as a net payout deposit.

2. Review Sales Receipt Deposit Account (Optional) so money posts to the intended Bank or Other Current Asset account.

3. Use Stripe payout reconciliation in the QuickBooks Manage drawer in Connected Apps to post a paid, standard, automatic Stripe bank payout as one QuickBooks Deposit covering settlement, fees, and disputes. Manual, instant, adjusted, or imbalanced payouts are held for review.

Configure deposit and income accounts in Map donations, designations, accounts, and classes. For payout reconciliation details, see QuickBooks Online integration overview.

Symptom: Sales receipts land in the wrong place, or service item revenue posts to the wrong income account.

Cause: Deposit and income accounts are separate. Deposits require a Bank or Other Current Asset account; revenue follows the income account on the selected Service Item. Changing item modes does not recategorize posted receipts: they retain their original item.

Fix:

1. On the Donations tab, set Sales Receipt Deposit Account (Optional) to a Bank or Other Current Asset account, then click Save Donation Settings.

2. If the field is blank, Gratona does not send a deposit account and QuickBooks uses its default deposit handling.

3. In Recipient items mode, set Service Item Income Account (Optional) on Accounting, then click Save Attachment Settings. This field is hidden in Existing QuickBooks item mode; review the selected item’s income account in QuickBooks instead.

4. If a previously saved deposit account is no longer available, choose a valid account again and save.

Symptom: Service items or sales receipt lines do not show the expected QuickBooks class.

Cause: Class tracking must be enabled in QuickBooks, and campaign entity classes can override the program default.

Fix:

1. Enable class tracking in QuickBooks Online.

2. On Accounting, set Service Item Class (Optional) in recipient mode, or Default Donation Class (Optional) under Donation Classes in shared mode. Click Save Attachment Settings.

3. For campaign programs with entity-specific class mapping, confirm the entity class when it should override the program default.

Symptom: Deleting or deactivating a record in one system removes or inactivates the linked record in the other system.

Cause: Deletion sync is controlled by two program toggles that default off.

Fix:

1. Open the program settings in the QuickBooks drawer.

2. Leave both delete toggles off unless finance intentionally wants linked deletes:

   • Delete/deactivate linked QuickBooks records when deleted in Gratona — linked Customers and recipient-mode Service Items become inactive in QuickBooks; sales receipts are deleted. Recipient deletion does not deactivate a configured shared Service Item.

   • Delete linked Gratona records when deleted/deactivated in QuickBooks — QuickBooks Customer deactivation can delete a linked donor, and sales receipt deletion can delete a linked donation. In Recipient items mode, Item deactivation can delete its linked recipient; shared items do not identify recipients.

3. Disconnect from the Integrations drawer clears the saved QuickBooks authorization and program setup, so reconnect and review configuration before syncing again. In Connected Apps, Disconnect retains connection history and record matches; Remove retires those matches after disconnection. Neither action reverses sales receipts or other accounting records already created in QuickBooks.

Symptom: Donors or donations show unexpected currency behavior after sync.

Cause: The donation currency must match the connected QuickBooks home currency and any explicitly assigned customer currency. Gratona uses its organization Base Currency in outbound customer create and qualifying update requests.

Fix: Review currency behavior in Synchronized Currency before expanding sync to more programs.