Troubleshoot QuickBooks synchronization

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 the QuickBooks drawer from Integrations.

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: Under Select a Program, Gratona shows No eligible programs found.

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 older Integrations drawer contains only program settings. Historical QuickBooks sync and its run history live only in the Connected Apps QuickBooks drawer.

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 refunded or non-positive, so Gratona skips sales receipt creation.

• 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 not refunded. Refunded and non-positive donations are skipped; Gratona does not automatically create QuickBooks refunds or voids.

2. Confirm the donor links to a QuickBooks customer and the gift resolves to a recipient service item, designation override, or Default Item for Additional Gifts (Optional).

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 account and income account are separate settings. Deposit accounts must be Bank or Other Current Asset. Income accounts sit on the service 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. On the Accounting tab, set Service Item Income Account (Optional), then click Save Attachment Settings.

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 the Accounting tab, set Service Item Class (Optional) and 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 — customers and service items become inactive in QuickBooks; sales receipts are deleted.

   • Delete linked Gratona records when deleted/deactivated in QuickBooks — QuickBooks customer or item deactivation can delete linked Gratona donors and recipients; sales receipt deletion can delete linked Gratona donations.

3. Remember that Disconnect QuickBooks removes all QuickBooks integration settings and mappings and cannot be undone. Disconnect does not undo sales receipts or other records already created in QuickBooks.

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

Cause: QuickBooks company currency and Gratona program currency can differ.

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