Penny Docs
Recurring transactions

Create Recurring Transaction

POST
/v1/households/{household_id}/recurring-transactions

Creates a recurring income or expense series for a household merchant. This defines an expected schedule; it does not initiate payments or create financial transactions.

Supply a positive amount and use type to distinguish income from expenses. Currency defaults to the household's reporting currency when omitted. Twice-monthly frequencies must omit start_date or set it to null; all other frequencies require an anchor date. Returns the new series.

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

merchant_id*Merchant Id
name*Name
amount*Amount
currency?|

ISO 4217 currency code. Defaults to the household's currency on create. PUT requires an explicit currency.

type?TransactionDirection
Default"expense"

Value in

  • "income"
  • "expense"
frequency*RecurringFrequency

Value in

  • "every_week"
  • "every_2_weeks"
  • "every_4_weeks"
  • "twice_monthly_1st_15th"
  • "twice_monthly_15th_last"
  • "every_month"
  • "every_2_months"
  • "every_3_months"
  • "every_4_months"
  • "every_6_months"
  • "every_year"
start_date?|null
notes?Notes
Default""

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/households/string/recurring-transactions" \  -H "Content-Type: application/json" \  -d '{    "merchant_id": "Mr9dL3xT6bQa",    "name": "Netflix",    "amount": "68.42",    "frequency": "every_week"  }'
{  "id": "Rt6wP4dM8xNc",  "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"  },  "name": "Netflix",  "amount": {    "amount": "68.42",    "currency": "USD"  },  "type": "income",  "frequency": "every_week",  "start_date": "2019-08-24",  "status": "active",  "end_date": "2019-08-24",  "notes": "Standard monthly plan"}

List Recurring Transactions GET

Lists the household's recurring income and expense series ordered by name, optionally filtered by status or merchant. Both active and cancelled series are…

Get Summary GET

Summarizes recurring income and expenses for a calendar month supplied as YYYY-MM. Returns expected expenses and income, plus expenses paid and income…