Penny Docs
Rules

Create Rule

POST
/v1/households/{household_id}/rules

Creates a transaction rule at the highest priority in the household. Define matching conditions and actions such as assigning a category or merchant, adding tags, or hiding transactions.

Set apply_to_existing: true to apply the new rule to existing visible transactions and return applied_count; otherwise, existing transactions are unchanged. Explicitly locked category and merchant choices are preserved, and tag actions are additive. Referenced accounts, categories, merchants, and tags must belong to the household.

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

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 POST "https://example.com/v1/households/string/rules" \  -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}

List Rules GET

Lists the household's active transaction rules in priority order, highest priority first, with their conditions and actions. Use this order when presenting…

Reorder Rules POST

Replaces the household's rule priority order and returns the rules in their new order. The first ID has the highest priority. Submit every active rule ID…