Run a historical QuickBooks sync
Updated 2 days ago
Backfill donors, recipients, and donations that existed before you connected QuickBooks Online. Historical QuickBooks sync lives in Connected apps: open your account menu, choose Organization settings > Connected apps, open the QuickBooks Online card, and click Manage. The older Integrations QuickBooks drawer shows Select a Program, but it does not contain historical run history.
Before you start
QuickBooks Online must be connected, and your role must allow management of organization integration settings. In Connected apps, open Manage and confirm the expected company under Connected to. If you are viewing a program, select Programs to return to the connection overview and historical controls. If the controls are unavailable, ask an organization administrator to review your access.
Review each selected program’s Item workflow first. Recipient items keeps the individual-Item workflow; Existing QuickBooks item uses the selected Service Item and omits per-recipient Item creation for shared programs. Classes and deposit accounts remain separate. See Use an existing QuickBooks Service Item for a program.
Donations still require a valid Customer link or an unambiguous email match. Customer sync can create new QuickBooks Customers when no match exists, and CSV-imported donors currently skip manual and historical Customer sync. Review linking before a bulk run if you want to use existing Customers only. A selected date range does not bypass payment, currency or accounting eligibility checks; pending or unsuccessful payments may wait or skip, while refunds and disputes require review.
Create a zero-write preview
The preview saves a Gratona plan showing what a backfill would do. It does not create or update records in QuickBooks.
Open your account menu and choose Organization settings > Connected apps.
On the QuickBooks Online card, click Manage. Confirm the intended company under Connected to in the drawer.
Scroll to Historical QuickBooks sync.
Optionally choose a From date and To date.
Select at least one record type: Customers, Service items, or Sales receipts. Create zero-write preview stays disabled until you select one.
Select the programs to include. Leaving Programs empty removes the program filter and can include eligible records across your organization. Customers are selected from donors with donations in the chosen date and program scope; donors without a matching donation are not included. A preview is limited to 500 records in total, so narrow the dates, programs, or record types if the scope is too large.
Click Create zero-write preview.
Approve the frozen plan
The preview classifies each record as create, update, link, skip, or conflict and freezes the plan against the currently connected QuickBooks company. Review the records and totals, then click Approve and queue frozen plan.
Reconcile donations already entered independently in QuickBooks before approval. Known linked receipts are recognized, but Customer links alone do not identify existing receipts, and separately entered receipts are not guaranteed to be detected as duplicates. Changing Item modes does not migrate posted receipts; existing receipts retain their Item.
Approval queues the frozen plan shown in the preview. If the connected company or a source record has changed, Gratona can reject approval or hold the affected checkpoint for review; create a new preview instead of assuming it will post. To change the date range, record types, or programs, create a new preview.
Open the execution run, not the dry-run preview
Approving creates a separate execution run. In Recent historical runs, click Refresh history, then open the backfill run, or correction run for an approved correction. The selected run details are labeled Execution run. Entries labeled dry run open a Frozen preview; previews save a local plan and never create or update records in QuickBooks.
Check each Sales receipt action and status
Each record in a run shows the QuickBooks object type, the Gratona record number, a reason code, the plan action, and the checkpoint status, with the currency and amount where present.
Plan actions:
create makes a new QuickBooks record
update changes an existing QuickBooks record
link recognizes an existing record mapping without creating or updating a QuickBooks record
skip and conflict take no action and do not call QuickBooks
Checkpoint statuses appear exactly as written:
Status | Meaning |
|---|---|
pending | Approved work not yet queued |
queued | Waiting to run |
processing | Running now |
processed | Completed successfully |
skipped | No write completed for this checkpoint; review the plan and reason |
failed | Did not complete |
needs_review | The record requires review; it may have been held before any QuickBooks write |
A completed run is not proof every receipt posted
A run finishes processing when no checkpoint is still pending, queued, or processing. Its status is failed if any checkpoint failed; otherwise it is completed, even when some checkpoints need review. Neither status proves every selected Sales receipt created a new QuickBooks record: update, link, skip, and conflict outcomes do not create new records. Review every failed and needs_review checkpoint before relying on the results in QuickBooks.
Retry failed or reviewable records
Records with a failed, needs_review, or skipped status show Retry record when the record can be retried. Retrying requeues that record and refreshes the run's status and counters. Resume failed checkpoints requeues retryable failed checkpoints and processes unfinished pending checkpoints.
If no execution run appears
Click Refresh history in Recent historical runs. If you approved a plan and the list still shows No historical runs yet. after refreshing, contact support.