Penny Docs
Rules

Update Rule

PUT
/v1/households/{household_id}/rules/{rule_id}

Replaces all matching conditions and actions of an existing rule while preserving its position in the priority order. Omitted fields reset to their schema defaults.

Set apply_to_existing: true to apply the updated rule to existing visible transactions and return applied_count. Category and merchant choices protected by field locks are preserved, and tag actions add to existing tags. Use the dry-run endpoint to preview matching transactions before updating.

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
rule_id*Rule Id

Request Body

application/json

filter_uncategorized?Filter Uncategorized
Defaultfalse
account_ids?array<string>|null
merchant_ids?array<string>|null
category_ids?array<string>|null
amount_filter?|null
penny_detailed_categories?array<>|null
name_conditions?array<>|null
set_category_id?string|null
set_merchant_id?string|null
apply_tag_ids?array<string>|null
set_hidden?Set Hidden
Defaultfalse
set_needs_review?boolean|null
apply_to_existing?Apply To Existing
Defaultfalse

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/v1/households/string/rules/string" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "Rl9cF3nV7sQa",  "priority": 1,  "account_ids": [    "Ac7kP2mN9qRs"  ],  "merchant_ids": [    "Mr9dL3xT6bQa"  ],  "category_ids": [    "Ct5nR8wY1jFu"  ],  "amount_filter": {    "direction": "income",    "operator": "equals",    "value": "68.42",    "value_upper": "100.00"  },  "penny_detailed_categories": [    "RENT_AND_UTILITIES_RENT"  ],  "name_conditions": [    {      "pattern": "BLUE BOTTLE",      "mode": "contains"    }  ],  "filter_uncategorized": true,  "set_category_id": "Ct5nR8wY1jFu",  "set_merchant_id": "Mr9dL3xT6bQa",  "apply_tag_ids": [    "Tg8qN1cK5rWd"  ],  "set_hidden": true,  "set_needs_review": true,  "applied_count": 18}

Delete Rule DELETE

Deletes a household rule so it is no longer applied to transactions. Changes previously made by the rule, including assigned categories and tags, are…

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…