QuickBooks Connection and Sync Troubleshooting

Use this workflow when QuickBooks data is stale, missing, or producing an unexpected grant result. Work in order: company and connection, sync job, history coverage, QuickBooks source, grant link, GrantLink allocation, then report scope.

Do not use writeback as a repair step: Settings > Permissions shows permission configuration, but all QuickBooks company-data mutations are currently disabled globally. Sync reads QuickBooks; troubleshooting corrections to source-controlled fields must be made in QuickBooks. Allocation and link corrections can still change GrantLink data.

Before You Start

Collect one example transaction with its QuickBooks company, type, date, document number or QuickBooks ID, amount, and expected grant. Do not share QuickBooks credentials or OAuth tokens.

Also confirm whether the problem affects:

• Every record, suggesting connection or sync failure
• One entity type, suggesting a partial job
• One old unchanged record, suggesting history coverage
• One grant, suggesting links or allocation
• One report, suggesting reporting scope

1. Confirm the Company and Connection

Open Settings > Sync. In Connection, verify the Active status, Company, Realm ID, Environment, and Connected on date.

If no connection appears, use Connect QuickBooks Online and Connect to QuickBooks. If GrantLink displays Reconnect QuickBooks for custom-field access, use Reconnect QuickBooks to approve the required scope. Reconnecting does not repair source coding or allocations.

Do not disconnect merely because one record is missing. Disconnect stops future reads and revokes the local authorization; it does not erase mirrored data or fix the record.

2. Read the Current Result

The status hero may show No sync yet, Syncing right now, Last sync failed, Sync finished with partial errors, or All caught up. Then inspect Recent activity, which shows the last 10 jobs.

Status	Meaning	Next action
Completed	The job completed without recorded entity failures	Continue to history, source, links, and allocation checks
Partial	Some entities succeeded and one or more failed	Select Details and identify the affected entity
Failed	The job did not complete	Read the visible error, then use Retry sync or Sync now when appropriate
Running or Pending	A background job still owns the connection	Wait; do not try to start a competing full sync or verification

In Details, record the entity, message, HTTP status, and whether GrantLink says Can retry, Needs review, or Retry status unknown. A Projects-only error can make a job partial while other data succeeds. Do not interpret Read or Upserted as dollars or as proof that a particular transaction was imported.

3. Choose the Smallest Refresh

Symptom	Control	Why
A recent record or old record edited recently is stale	Sync now	Pulls recent QuickBooks changes since the prior cursor
Setup or recent historical data has gaps	Run full sync	Re-reads the configured bounded history
An unchanged record predates bounded coverage	Import complete history, where available	Reads from a selected first transaction date
An entity failed transiently in a partial job	Sync again	Retries current changes without unnecessarily widening history

For a full sync, Full-sync history window accepts 30–4,000 days and defaults to 365. Select Save before Run full sync; saving alone imports nothing. In the confirmation, leave Also re-apply allocation rules off when you only want to refresh the mirror. Turn it on only if current rules should run against refreshed records.

Where Import complete history is enabled, it replaces the bounded history-window input. Choose a valid first transaction date no later than today and select Import history. If GrantLink requires a recent change cursor, run Sync now first. Repeated incremental syncs cannot recover an unchanged transaction that was never imported.

4. Verify the QuickBooks Source

Open the authoritative transaction in the same QuickBooks company. Inspect the relevant line, not only the header. Confirm:

• Transaction type, date, amount, and account
• Vendor or customer
• Customer or sub-customer/job
• Class and Location/department
• Project, where available
• Whether the record was deleted, voided, or changed after the last successful sync

Correct source-controlled values in QuickBooks, then select Sync now. Do not create a duplicate GrantLink grant, receipt, or allocation to conceal a source error.

5. Verify the Grant's QuickBooks Links

If the transaction is visible in GrantLink but has no grant—or the wrong grant—open the grant and review QuickBooks links. Confirm Expenses uses the intended source records for costs and Money received uses the intended source records for receipts.

Links are per grant. They classify synced data; they do not authorize QuickBooks writes. A completed sync cannot compensate for a missing, overlapping, or incorrect Customer, Project, Class, or Location link.

6. Review GrantLink Allocations

An ordinary successful or partial sync schedules allocation-rule processing. Therefore, sync can create or change allocations inside GrantLink even though it never changes QuickBooks source data. A full sync skips rule application only when Also re-apply allocation rules is left off; this does not undo existing allocations.

Review the transaction in Ledger and the grant's Allocations. Check the effective grant, amount or percentage, budget line, status, rule or manual source, and lifecycle history. Correct a GrantLink reporting decision in GrantLink; correct accounting facts in QuickBooks.

See Allocating Transactions to Grants for the allocation workflow.

7. Check Report Scope

If the source, mirror, link, and allocation are correct, compare the report's grant, funder, reporting period, transaction date, allocation status, split amount, and saved output version. A previously generated report may need regeneration after a correction.

See Why Your Grant Report Doesn't Match QuickBooks for reconciliation guidance.

Symptom Guide

Symptom	Most likely boundary	Verify next
Nothing updates	Connection or failed job	Connection, status hero, newest Recent activity row
One data type is missing	Partial entity failure	Details > Sync issues
A recent edit is stale	Incremental change flow	Sync now, then source record
One old unchanged record is absent	History coverage	Date versus bounded window or complete-history start date
Record exists but has no or wrong grant	QuickBooks link or allocation	Grant QuickBooks links, then effective allocation
Allocation changed after sync	Allocation rule	Rule, allocation lifecycle, and whether rules were applied
Only one report is wrong	Report scope or saved output	Dates, grant, status, split, and regeneration

Verify the Repair

1. Confirm the newest Recent activity row has the expected Mode and a new Started time.
2. Require Completed, or document and assess every Partial issue that affects your result.
3. Reopen the mirrored transaction and compare it with QuickBooks.
4. Recheck the grant link and effective allocation.
5. Regenerate or rerun the affected report and reconcile the amount.

Evidence for Support

Provide only bounded evidence:

1. GrantLink organization and grant name
2. QuickBooks company name and realm ID—never credentials or tokens
3. Status hero text and newest job's Started, Mode, and Status
4. Read, Upserted, and Duration as context, not proof of the missing record
5. Any Sync issues entity, message, HTTP status, and retry label
6. Example transaction type, date, document number or QuickBooks ID, and amount
7. Expected Customer, Project, Class, or Location and grant link
8. History-window value or complete-history start date and refresh attempted
9. Expected allocation and report scope

Do not send passwords, access or refresh tokens, unrelated person data, or an unbounded ledger export.