Stripe

Fetch balance transactions from Stripe, including automatic payout grouping and synthetic fee rows.

Setup

Generate a restricted API key at Stripe Dashboard > API keys with read access to Balance Transactions and Payouts.

export STRIPE_API_KEY=sk_live_...

Usage

vgrid fetch stripe --from 2026-01-01 --to 2026-02-01 --out stripe.csv

For Stripe Connect sub-accounts, pass --account:

vgrid fetch stripe --from 2026-01-01 --to 2026-02-01 --account acct_1234 --out stripe.csv

Options

Flag	Description	Default
--from	Start date inclusive (YYYY-MM-DD)	required
--to	End date exclusive (YYYY-MM-DD)	required
--api-key	Stripe secret key	STRIPE_API_KEY env
--account	Stripe Connect account ID (acct_...)	—
--out	Output CSV path	stdout
-q / --quiet	Suppress progress messages	off

Type mapping

Stripe type	Canonical type
charge, payment	charge
payout	payout
stripe_fee, application_fee	fee
refund	refund
anything else	adjustment

Unmapped types include the original Stripe type in the description (e.g. [stripe_type: transfer]).

Date handling

• effective_date — created timestamp converted to YYYY-MM-DD (UTC)
• posted_date — available_on timestamp converted to YYYY-MM-DD (UTC)

Notes

Synthetic fee rows. When a balance transaction has a non-zero fee and is not itself a fee type, VisiGrid emits an additional fee row with source_id = "{source_id}_fee" and amount = -fee.

Payout grouping. After fetching all transactions, VisiGrid makes per-payout API calls to resolve which balance transactions belong to each payout. Transactions and their synthetic fee rows are tagged with group_id = po_xxx.

Pagination. Cursor-based (starting_after, 100 items per page) with stuck-cursor detection.

Sort order. created ascending, then source_id ascending.