Penny Docs
Spending

Get Merchant Breakdown

GET
/v1/households/{household_id}/analytics/merchant-breakdown

Aggregates transactions by merchant over an inclusive date range and returns signed totals in the household's reporting currency with transaction counts. Results are ordered by the absolute value of the total, largest first; unknown merchants appear with null merchant fields.

Filter by accounts, tags, or categories. 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
tag_ids?array<string>|null
account_ids?array<string>|null
category_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/merchant-breakdown?start_date=2019-08-24&end_date=2019-08-24"
{  "merchants": [    {      "merchant_id": "Mr9dL3xT6bQa",      "merchant_name": "Blue Bottle Coffee",      "amount": {        "amount": "68.42",        "currency": "USD"      },      "transaction_count": 18    }  ]}

Get Cashflow By Period GET

Returns income, expenses, and net cashflow for each calendar period intersecting an inclusive date range, optionally filtered by accounts or tags. Amounts…

Get Category Breakdown GET

Breaks down income and expenses by category group and category over an inclusive date range, with totals and percentage shares. Ungrouped categories and…