QuickBooks Online

Fetch bank transactions from QuickBooks Online, including deposits, purchases, and transfers.

Setup

Create a QuickBooks app at developer.intuit.com and complete the OAuth 2.0 flow. Save your credentials to a JSON file:

{
  "client_id": "AB...",
  "client_secret": "...",
  "access_token": "eyJ...",
  "refresh_token": "AB...",
  "realm_id": "123456789"
}

VisiGrid automatically refreshes expired access tokens and writes the updated credentials back to the file.

Caution

On Unix systems, VisiGrid warns if your credentials file is readable by group or world. Use chmod 600 credentials.json to restrict access.

Usage

vgrid fetch qbo --credentials qbo-creds.json --account "Business Checking" \
  --from 2026-01-01 --to 2026-02-01 --out qbo.csv

Or pass the access token directly (no auto-refresh):

vgrid fetch qbo --access-token eyJ... --realm-id 123456789 \
  --account-id 42 --from 2026-01-01 --to 2026-02-01 --out qbo.csv

Options

Flag	Description	Default
--from	Start date inclusive (YYYY-MM-DD)	required
--to	End date exclusive (YYYY-MM-DD)	required
--credentials	Path to OAuth2 JSON file	—
--access-token	Direct access token (requires --realm-id)	—
--realm-id	QBO company realm ID	—
--account	Bank account name (resolved to ID)	—
--account-id	Bank account ID directly	—
--include	Entity types to fetch	deposit,purchase,transfer
--out	Output CSV path	stdout
-q / --quiet	Suppress progress messages	off
--sandbox	Use QBO sandbox API	off

Type mapping

QBO entity	PaymentType	Canonical type
Deposit	—	deposit
Purchase	Cash	withdrawal
Purchase	Check	check
Purchase	any other	expense
Transfer	—	transfer (signed by direction)

Purchase amounts are negated (outflow). Transfer sign depends on whether your account is the source or destination.

Date handling

• effective_date — TxnDate from QuickBooks
• posted_date — same as effective_date (QBO does not distinguish)

Notes

Account resolution. --account performs a query for the bank account name. Apostrophes in account names are escaped automatically. If the name is ambiguous, VisiGrid shows all matching accounts with their fully qualified names.

Client-side account filtering. QBO’s query API does not support filtering deposits and purchases by bank account, so VisiGrid fetches all transactions in the date range and filters client-side by account ID.

--include filter. Comma-separated list of entity types: deposit, purchase, transfer. Defaults to all three.

source_id format. Prefixed with the entity type: deposit:101, purchase:201, transfer:301.

Pagination. Offset-based (STARTPOSITION / MAXRESULTS 1000) ordered by TxnDate ASC, Id ASC.

Sort order. effective_date ascending, then source_id ascending.