Gusto

Fetch processed payroll data from Gusto, split into net pay, tax, and other debit components.

Setup

Create a Gusto app at dev.gusto.com and complete the OAuth 2.0 flow. Save your credentials to a JSON file:

{
  "client_id": "...",
  "client_secret": "...",
  "access_token": "eyJ...",
  "refresh_token": "...",
  "company_uuid": "..."
}

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

Usage

vgrid fetch gusto --credentials gusto-creds.json \
  --from 2026-01-01 --to 2026-02-01 --out gusto.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 --company-uuid)	—
--company-uuid	Gusto company UUID	—
--out	Output CSV path	stdout
-q / --quiet	Suppress progress messages	off

Type mapping

Each processed payroll expands into exactly 3 canonical rows:

Row	type	Amount
Net pay	payroll_net	-net_pay_debit
Tax	payroll_tax	-tax_debit
Other (fees/misc)	payroll_other	-(company_debit - net_pay - tax)

All amounts are negative (outflow from the company bank account).

Date handling

• effective_date — check_date from the Gusto payroll
• posted_date — same as effective_date (Gusto does not distinguish)

Notes

3-row expansion. Each payroll becomes 3 rows sharing the same group_id = payroll:{uuid}. The source_id values are payroll:{uuid}:net, payroll:{uuid}:tax, and payroll:{uuid}:other.

Date range limit. Maximum span of 366 days. VisiGrid errors if the range exceeds this.

Status filter. Only payrolls with processing_status = processed are included.

Pagination. Page-based (100 payrolls per page).

Sort order. effective_date ascending, then source_id ascending.