Penny Docs
Spending

Get Accumulated Spending

GET
/v1/households/{household_id}/analytics/accumulated-spending

Summarizes income and expenses over an inclusive date range, with transaction counts and category breakdowns. Amounts and amount filters use the household's reporting currency.

Hidden and deleted transactions, transactions on deleted accounts, split parents, and transfers are excluded; pending transactions are included. Totals are netted within each category, with positive category totals reported as income and negative totals as expenses.

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
merchant_ids?array<string>|null
tag_ids?array<string>|null
category_ids?array<string>|null
category_group_ids?array<string>|null
account_ids?array<string>|null
uncategorized?boolean|null
unknown_merchant?boolean|null
need_review?boolean|null
min_amount?|

Interpreted in the household's currency. Transaction amounts in other currencies are converted before the filter is applied. Amounts and thresholds are rounded to the currency minor unit using half-even rounding for comparison.

max_amount?|

Interpreted in the household's currency. Transaction amounts in other currencies are converted before the filter is applied. Amounts and thresholds are rounded to the currency minor unit using half-even rounding for comparison.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/households/string/analytics/accumulated-spending?start_date=2019-08-24&end_date=2019-08-24"
{  "income": {    "total": {      "amount": "68.42",      "currency": "USD"    },    "count": 42,    "category_breakdown": [      {        "category_id": "Ct5nR8wY1jFu",        "category_name": "Coffee & Dining",        "total": {          "amount": "68.42",          "currency": "USD"        },        "count": 18,        "emoji": "☕️"      }    ]  },  "expenses": {    "total": {      "amount": "68.42",      "currency": "USD"    },    "count": 42,    "category_breakdown": [      {        "category_id": "Ct5nR8wY1jFu",        "category_name": "Coffee & Dining",        "total": {          "amount": "68.42",          "currency": "USD"        },        "count": 18,        "emoji": "☕️"      }    ]  }}

Update Recurring Transaction PUT

Replaces a recurring series' editable details and returns the updated series. Supply its complete definition, including currency, status, and notes.…

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…