Penny Docs
Spending

Get Cashflow By Period

GET
/v1/households/{household_id}/analytics/cashflow-by-period

Returns income, expenses, and net cashflow for each calendar period intersecting an inclusive date range, optionally filtered by accounts or tags. Amounts use the household's reporting currency: income is positive, expenses are negative, and net is their sum.

Empty periods have zero totals. Period boundaries cover the full calendar period, but totals include only the requested dates. is_complete indicates whether the period has ended in the household's timezone. Hidden and deleted transactions, transactions on deleted accounts, split parents, and transfers are excluded; pending transactions are included.

Authorization

PersonalApiToken
AuthorizationBearer <token>

Use your personal API token (penny_pat_…) as the bearer credential. Enter the token only; the client adds the Bearer prefix. Read-only tokens permit read requests. Read/write tokens remain limited by your current household membership and role. See https://penny.finance/docs/api#authentication for setup.

In: header

Path Parameters

household_id*Household Id

Query Parameters

start_date*Start Date
Formatdate
end_date*End Date
Formatdate
time_segment*TimeSegment

Value in

  • "daily"
  • "monthly"
  • "quarterly"
  • "yearly"
account_ids?array<string>|null
tag_ids?array<string>|null

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/households/string/analytics/cashflow-by-period?start_date=2019-08-24&end_date=2019-08-24&time_segment=daily"
{  "periods": [    {      "start_date": "2019-08-24",      "end_date": "2019-08-24",      "income": {        "amount": "68.42",        "currency": "USD"      },      "expenses": {        "amount": "68.42",        "currency": "USD"      },      "net": {        "amount": "68.42",        "currency": "USD"      },      "is_complete": true    }  ]}

Get Spending By Period GET

Groups income and expenses into daily, monthly, quarterly, or yearly periods over an inclusive date range. Each period includes totals, counts, and category…

Get Merchant Breakdown GET

Aggregates transactions by merchant over an inclusive date range and returns signed totals in the household's reporting currency with transaction counts.…