Penny Docs
Households

Update Household

PATCH
/v1/households/{household_id}

Updates a household's name, reporting currency, or timezone and returns the updated household. Only the household owner can make this change.

Send only the fields you want to change. Changing the reporting currency affects converted totals; financial accounts retain their native currencies. The timezone determines household-local dates used in reports and recurring transactions.

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

Request Body

application/json

name?Name
Lengthlength <= 255
currency?Currency

Value in

  • "AED"
  • "AFN"
  • "ALL"
  • "AMD"
  • "AOA"
  • "ARS"
  • "AUD"
  • "AWG"
  • "AZN"
  • "BAM"
  • "BBD"
  • "BDT"
  • "BHD"
  • "BIF"
  • "BMD"
  • "BND"
  • "BOB"
  • "BOV"
  • "BRL"
  • "BSD"
  • "BTN"
  • "BWP"
  • "BYN"
  • "BZD"
  • "CAD"
  • "CDF"
  • "CHE"
  • "CHF"
  • "CHW"
  • "CLF"
  • "CLP"
  • "CNY"
  • "COP"
  • "COU"
  • "CRC"
  • "CUP"
  • "CVE"
  • "CZK"
  • "DJF"
  • "DKK"
  • "DOP"
  • "DZD"
  • "EGP"
  • "ERN"
  • "ETB"
  • "EUR"
  • "FJD"
  • "FKP"
  • "GBP"
  • "GEL"
  • "GHS"
  • "GIP"
  • "GMD"
  • "GNF"
  • "GTQ"
  • "GYD"
  • "HKD"
  • "HNL"
  • "HTG"
  • "HUF"
  • "IDR"
  • "ILS"
  • "INR"
  • "IQD"
  • "IRR"
  • "ISK"
  • "JMD"
  • "JOD"
  • "JPY"
  • "KES"
  • "KGS"
  • "KHR"
  • "KMF"
  • "KPW"
  • "KRW"
  • "KWD"
  • "KYD"
  • "KZT"
  • "LAK"
  • "LBP"
  • "LKR"
  • "LRD"
  • "LSL"
  • "LYD"
  • "MAD"
  • "MDL"
  • "MGA"
  • "MKD"
  • "MMK"
  • "MNT"
  • "MOP"
  • "MRU"
  • "MUR"
  • "MVR"
  • "MWK"
  • "MXN"
  • "MXV"
  • "MYR"
  • "MZN"
  • "NAD"
  • "NGN"
  • "NIO"
  • "NOK"
  • "NPR"
  • "NZD"
  • "OMR"
  • "PAB"
  • "PEN"
  • "PGK"
  • "PHP"
  • "PKR"
  • "PLN"
  • "PYG"
  • "QAR"
  • "RON"
  • "RSD"
  • "RUB"
  • "RWF"
  • "SAR"
  • "SBD"
  • "SCR"
  • "SDG"
  • "SEK"
  • "SGD"
  • "SHP"
  • "SLE"
  • "SOS"
  • "SRD"
  • "SSP"
  • "STN"
  • "SVC"
  • "SYP"
  • "SZL"
  • "THB"
  • "TJS"
  • "TMT"
  • "TND"
  • "TOP"
  • "TRY"
  • "TTD"
  • "TWD"
  • "TZS"
  • "UAH"
  • "UGX"
  • "USD"
  • "USN"
  • "UYI"
  • "UYU"
  • "UYW"
  • "UZS"
  • "VED"
  • "VES"
  • "VND"
  • "VUV"
  • "WST"
  • "XAD"
  • "XAF"
  • "XAG"
  • "XAU"
  • "XBA"
  • "XBB"
  • "XBC"
  • "XBD"
  • "XCD"
  • "XCG"
  • "XDR"
  • "XOF"
  • "XPD"
  • "XPF"
  • "XPT"
  • "XSU"
  • "XTS"
  • "XUA"
  • "XXX"
  • "YER"
  • "ZAR"
  • "ZMW"
  • "ZWG"
timezone?Timezone

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/households/string" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "Hh4vK8pQ2sLm",  "name": "Chen Household",  "currency": "AED",  "timezone": "America/Los_Angeles",  "image_url": "https://cdn.penny.finance/households/Hh4vK8pQ2sLm.png",  "role": "owner",  "preferences": {    "show_recurring_suggestions": true,    "show_advanced_details": true  },  "access_status": "available"}

Create Household POST

Creates a household with the supplied name, reporting currency, and timezone, and makes the authenticated user its owner. The household is initialized with…

Delete Household DELETE

Permanently deletes the household and its associated financial data for every member. Only the household owner can delete it, including when subscription…