Penny Docs
Merchants

Create Merchant

POST
/v1/households/{household_id}/merchants

Creates a merchant in the household for use on transactions and recurring series. Returns the merchant with its resolved image URL and usage counts.

The name must be unique among the household's active merchants. Supply website when available to help identify the merchant.

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
website?|null

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/merchants" \  -H "Content-Type: application/json" \  -d '{    "name": "Blue Bottle Coffee"  }'
{  "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,  "recurring_transaction_count": 1}

List Merchants GET

Lists all active merchants in the household, including their display images and counts of visible transactions and recurring series. The response is not…

Get Merchant GET

Retrieves an active household merchant with its website, resolved image URL, and transaction and recurring-series counts. Returns merchantnotfound if the…