Spending

Get Spending Treemap

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

Breaks spending over an inclusive date range down by category group, category, and merchant, for drawing as a treemap. Categories that net to spending appear under their expense group, or in ungrouped_categories when they have none; uncategorized debits appear there with a null category. Each category lists the merchants it was spent at, with unknown merchants as null merchant fields.

Amounts are positive magnitudes in the household's reporting currency, and every percentage is a share of total. A merchant whose refunds exceed its purchases within a category is omitted, so a category's merchants can add up to more than the category. Items are ordered largest first, with uncategorized spending last. 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

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/households/string/analytics/spending-treemap?start_date=2019-08-24&end_date=2019-08-24"
{  "start_date": "2019-08-24",  "end_date": "2019-08-24",  "total": {    "amount": "68.42",    "currency": "USD"  },  "groups": [    {      "group_id": "Cg2mV7pL4zXe",      "group_name": "Everyday Expenses",      "amount": {        "amount": "68.42",        "currency": "USD"      },      "percentage": "68.42",      "transaction_count": 42,      "categories": [        {          "category_id": "Ct5nR8wY1jFu",          "category_name": "Coffee & Dining",          "emoji": "☕️",          "amount": {            "amount": "68.42",            "currency": "USD"          },          "percentage": "68.42",          "transaction_count": 18,          "merchants": [            {              "merchant_id": "Mr9dL3xT6bQa",              "merchant_name": "Blue Bottle Coffee",              "image_url": "https://cdn.penny.finance/merchants/blue-bottle-coffee.png",              "amount": {                "amount": "68.42",                "currency": "USD"              },              "percentage": "68.42",              "transaction_count": 9            }          ]        }      ]    }  ],  "ungrouped_categories": [    {      "category_id": "Ct5nR8wY1jFu",      "category_name": "Coffee & Dining",      "emoji": "☕️",      "amount": {        "amount": "68.42",        "currency": "USD"      },      "percentage": "68.42",      "transaction_count": 18,      "merchants": [        {          "merchant_id": "Mr9dL3xT6bQa",          "merchant_name": "Blue Bottle Coffee",          "image_url": "https://cdn.penny.finance/merchants/blue-bottle-coffee.png",          "amount": {            "amount": "68.42",            "currency": "USD"          },          "percentage": "68.42",          "transaction_count": 9        }      ]    }  ]}

Get Cashflow Sankey GET

Describes how income flows into spending and savings over an inclusive date range, as the nodes and links of a Sankey diagram. Income categories flow into a…

List Historical Balances GET

Retrieves daily balance history for the household, optionally restricted to specific accounts and an inclusive date range. Daily totals use the household's…