QuickBooks Permissions and Current Writeback Availability

GrantLink separates how records map to QuickBooks from whether GrantLink may write company data. Use Settings > QuickBooks Mapping to describe and import relationships. Use Settings > Permissions to save the organization-wide writeback policy.

Current availability: QuickBooks remains the accounting source of truth. GrantLink can sync, report, link existing entities, and save GrantLink reporting decisions, but its company-data writers are currently disabled globally during a control-plane rebuild. Saving Selected writebacks or Full writeback / automation does not make those writes operational today.

Before You Start

• Connect and sync QuickBooks first. See Connecting QuickBooks Online and QuickBooks Connection and Sync Troubleshooting.
• Use an organization Admin role to change Settings > Permissions. The server verifies the Clerk admin or owner role; hiding or showing a control is not the authorization boundary.
• Treat mapping and permission changes as organization-wide configuration, not as a replacement for accounting approval.
• Keep making required accounting changes in QuickBooks, then sync GrantLink.

Choose a Source-of-Truth Mode

Open Settings > Permissions. The page shows three modes:

Mode shown in GrantLink	Saved policy behavior	Current operational result
Read-only reporting	Clears every write category. GrantLink can sync, link existing entities, and report without changing QuickBooks.	Matches the current global boundary.
Selected writebacks	Lets an Admin select individual categories; unselected categories remain denied.	The choices can be saved, but all company-data writes are still blocked globally.
Full writeback / automation	Saves all visible categories as allowed; grant-level toggles may still narrow intended behavior.	It does not override the global block.

If no explicit policy has been saved, the page displays a notice. The effective backend default is fail-safe read-only. Select the intended policy and choose Save changes. A successful save records the policy and audit event; it does not test or perform a QuickBooks write.

Review Every Selected-Writeback Category

In Selected writebacks, Allowed writebacks displays eight categories:

Master data

• Create or update QuickBooks Online grant entities: a Class, Customer, or Project representing a grant.
• Create or update QuickBooks Online funder customers: the Customer representing a funder.

Transactions

• Update QuickBooks Online transaction grant tags: Class, Customer, or Project tags on synced transactions.
• Create allocation journal entries: journal entries associated with expense allocations.
• Create reversing journal entries: reversals associated with released allocations.

Billing & overhead

• Post indirect cost journal entries: indirect-cost allocation journal entries.
• Create claim invoices: QuickBooks invoices from Claims Builder.
• Write approved QuickBooks Online custom fields: approved fields such as a budget category code.

These controls express intended policy only. They are not proof that a writer exists, is enabled, or completed. In particular, do not infer that a Ledger allocation changed a transaction tag or posted a journal entry.

Configure QuickBooks Mapping Separately

Open Settings > QuickBooks Mapping. The page links back to QuickBooks Permissions and explicitly treats mapping as separate from writeback.

Current mapping surfaces include:

• Mapping configuration: describes how GrantLink entities map to QuickBooks. Funders map to Customer. Shared settings do not relink existing grants; grant links are selected on each grant. Projects require QuickBooks Projects capability.
• Restriction release accounts: when this feature is available, identifies release and offset accounts used to recognize reclassifications.
• Functional expense tracking: selects the QuickBooks dimension used for Program, Administration, and Fundraising reporting: Class, Department, or None.
• Class visibility in GrantLink: hides or restores synced classes in GrantLink only. It does not hide, deactivate, or edit them in QuickBooks.
• Import grants from QuickBooks: Scan classes or Re-scan classes, review suggested bundles, save selections, then import accepted grants and class links.

Mapping configuration saves GrantLink organization metadata; importing creates or links GrantLink records from existing QuickBooks data. Neither operation grants permission to mutate QuickBooks company data.

Understand the Administration Boundary

Settings > Permissions is Admin-only at the API: all members may read the effective policy, but only an Admin can save it. The page states that changes apply to every organization member.

The current QuickBooks Mapping implementation is more granular:

• An authenticated organization member can currently save the shared mapping configuration.
• Class visibility changes and the class import plan's scan/draft, approval, and apply operations are Admin-only at their APIs.
• Therefore, do not describe the entire Mapping page as uniformly Admin-only. Organizations that require tighter review should restrict who changes mapping configuration through their own operating procedure until the UI/API boundary is aligned.

Know the Global Fail-Closed Boundary

The saved policy evaluator understands read_only, selected, and full, but the current execution guard deliberately returns not allowed for every company-data operation. The legacy writers in the QuickBooks and mapping backends—including grant entities, funder customers, transaction tags, custom fields, claims, and allocation, reversal, or indirect-cost journal entries—fail closed.

This produces an important distinction:

1. Policy configuration is available: an Admin can save future intent.
2. Read and local workflows are available: syncing, linking existing entities, importing into GrantLink, reports, notes, budget categories, and local reporting allocations can proceed.
3. QuickBooks company-data mutation is unavailable: no visible mode or category bypasses the global writer boundary.

If a workflow reports the control-plane rebuild error, do not repeatedly retry or assume a partial QuickBooks update. Verify QuickBooks directly. Make the accounting change there and sync again.

Verify a Safe Configuration

1. In Settings > Permissions, confirm the displayed mode and save only if you are an Admin.
2. Reopen the page and confirm the saved badge and categories.
3. In Settings > QuickBooks Mapping, verify dimensions, links, and visibility without expecting QuickBooks changes.
4. Sync, then inspect the relevant grant or Ledger source details.
5. Verify accounting state in QuickBooks itself. A GrantLink success message for a local report, mapping, or allocation is not evidence of a QuickBooks write.

For transaction-level effects, see The Ledger Workflow. For allocation accounting boundaries, see Allocating Transactions to Grants.