Overview The Merchants API provides read-only access to merchants associated with your family. This includes both family-owned merchants and provider merchants that are assigned to your transactions.
Authentication Requires read or read_write scope.
Endpoints List All Merchants Retrieve all merchants available to the family.
Response Returns an array of merchant objects sorted alphabetically.
[ { "id" : "123" , "name" : "Whole Foods" , "type" : "ProviderMerchant" , "created_at" : "2024-01-15T10:30:00Z" , "updated_at" : "2024-01-15T10:30:00Z" }, { "id" : "456" , "name" : "Local Coffee Shop" , "type" : "FamilyMerchant" , "created_at" : "2024-02-20T14:22:00Z" , "updated_at" : "2024-02-20T14:22:00Z" } ]
Unique identifier for the merchant
Display name of the merchant
Merchant type: FamilyMerchant or ProviderMerchant
ISO 8601 timestamp when the merchant was created
ISO 8601 timestamp when the merchant was last updated
Example Request curl -X GET https://your-domain.com/api/v1/merchants \ -H "X-Api-Key: your_api_key_here"
Get a Specific Merchant Retrieve a single merchant by ID.
The unique identifier of the merchant
Response Returns a single merchant object.
{ "id" : "123" , "name" : "Whole Foods" , "type" : "ProviderMerchant" , "created_at" : "2024-01-15T10:30:00Z" , "updated_at" : "2024-01-15T10:30:00Z" }
Example Request curl -X GET https://your-domain.com/api/v1/merchants/123 \ -H "X-Api-Key: your_api_key_here"
Merchant Types FamilyMerchant : Merchants created directly by your family for manual transactions.ProviderMerchant : Merchants automatically created from connected financial institutions (Plaid, SimpleFIN, etc.).
Error Responses { "error" : "Merchant not found" }
500 Internal Server Error
{ "error" : "Failed to fetch merchants" }
{ "error" : "unauthorized" , "message" : "Access token or API key is invalid, expired, or missing" }
Notes
The merchants endpoint returns a deduplicated list of both family-owned and provider merchants
Merchants are automatically sorted alphabetically by name
This is a read-only endpoint - merchant creation and updates happen automatically through transaction imports