Penny Docs
Transactions

List Transactions

GET
/v1/households/{household_id}/transactions

Lists household transactions newest date first, with related account, merchant, category, and tag details and daily totals in the household's reporting currency. By default, hidden and deleted transactions, split parents, and transactions on deleted accounts are excluded; pending transactions are included.

Set hidden=true or deleted=true to browse those transactions; deleted=true takes precedence. Date bounds are inclusive, and amount filters use the household's currency. uncategorized=true overrides category IDs, and unknown_merchant=true overrides merchant IDs.

Pass next_cursor as cursor with the same filters to continue. Pages keep complete days together, so a response can exceed min_limit. When filters change, start without a cursor. Daily sums exclude transfers, even when transfer transactions appear in the results.

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

cursor?string|null
min_limit?Min Limit
Range1 <= value <= 200
Default50
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.

amount_equal?|

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.

search?string|null
start_date?|null
end_date?|null
need_review?boolean|null
pending?boolean|null
has_notes?boolean|null
uncategorized?boolean|null
unknown_merchant?boolean|null
deleted?boolean|null
hidden?boolean|null
merchant_ids?array<string>|null
category_ids?array<string>|null
tag_ids?array<string>|null
account_ids?array<string>|null

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/households/string/transactions"
{  "transactions": [    {      "id": "Tx3fJ9mS6vBa",      "original_name": "BLUE BOTTLE COFFEE #047",      "user_name": "Morning coffee",      "amount": {        "amount": "68.42",        "currency": "USD"      },      "native_amount": {        "amount": "68.42",        "currency": "USD"      },      "lat": 37.7764,      "lon": -122.4231,      "pending": false,      "penny_taxonomy": "FOOD_AND_DRINK_COFFEE",      "account": {        "id": "Ac7kP2mN9qRs",        "mask": "4821",        "name": "Everyday Checking",        "type": "depository",        "current_balance": {          "amount": "68.42",          "currency": "USD"        },        "currency": "USD",        "household_id": "Hh4vK8pQ2sLm",        "user_name": "Daily spending"      },      "household_finance_category": {        "id": "Ct5nR8wY1jFu",        "name": "Coffee & Dining",        "emoji": "☕️",        "category_type": "income",        "group_id": "Cg2mV7pL4zXe"      },      "merchant": {        "id": "Mr9dL3xT6bQa",        "name": "Blue Bottle Coffee",        "website": "https://www.bluebottlecoffee.com/",        "image_url": "https://cdn.penny.finance/merchants/blue-bottle-coffee.png",        "default_image_url": "https://cdn.penny.finance/merchants/default-coffee.png",        "transaction_count": 18      },      "image_url": "https://cdn.penny.finance/merchants/blue-bottle-coffee.png",      "image_kind": "merchant",      "tags": [        {          "id": "Tg8qN1cK5rWd",          "name": "Work meals",          "color": "#6D5BD0"        }      ],      "is_deleted": false,      "is_hidden": false,      "pending_transaction_id": "Tx3fJ9mS6vBa",      "date": "2019-08-24",      "need_review": false,      "possible_duplicate_ids": [        "Tx3fJ9mS6vBa"      ],      "notes": "Coffee with Sam before work",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z",      "name": "Morning coffee",      "split_from_transaction_id": "Tx3fJ9mS6vBa",      "split_child_ids": [        "Tx3fJ9mS6vBa"      ],      "is_recurring": false    }  ],  "daily_sums": [    {      "date": "2019-08-24",      "amount": {        "amount": "68.42",        "currency": "USD"      }    }  ],  "next_cursor": "eyJkYXRlIjoiMjAyNi0wOC0xMyIsImlkIjoiVHg4YVEya0w1blJlIn0",  "has_more": true}

Upload Account Image PUT

Uploads or replaces a financial account's custom image and returns its display URL. This image overrides the account's default institution or provider…

Create Transaction POST

Creates a posted transaction on a non-deleted manual account in the household. The transaction uses the account's currency; positive amounts represent…