analyze_discretionary_spending
ChatGPTSums posted expenses over a number of months (default 3) and labels categories discretionary or essential by name. Returns total, discretionary, and essential spending, the top categories with a monthly average and 25% and 50% reduction figures, a discretionary breakdown, and the top merchants.
check_affordability
ChatGPTRead-only preview of whether a purchase amount fits available funds. can_afford and available_for_purchase compare the amount with the checking balance (or the named account) minus a safety buffer. Also returns budget_category and budget_left (what that category has left this month; budget_category is present when a merchant maps to one), left_after_bills (what this month's budget has left after the bills still due), upcoming_bills_total, data_fresh (whether the bank data and budget figures are current; null when unknown), data_as_of (the oldest bank sync), and advice (those figures in plain words, including when bank data is stale or the charge is recurring). Optional inputs: account, merchant, category, recurring. This is a preview only: it holds nothing, approves nothing and spends nothing.
compare_periods
ChatGPTCompares spending between two periods. period1 and period2 accept a month (YYYY-MM), a date, or a named period such as this_month or last_month. Optional category limits the comparison. Returns the spending difference, percent change, and whether spending increased, decreased, or was unchanged.
draft_claim
ChatGPTDrafts a return request, warranty claim, or price-adjustment message for one scanned receipt. Inputs are receipt_id and optional kind: "return" (default), "warranty", or "price_adjustment". For price_adjustment, product names the item when the receipt has more than one lower price still inside its return window. Returns subject, body, missing (bracketed placeholders), and how_to_send. Does not send the message, contact the merchant, or move money.
get_account_balance
ChatGPTReturns the current balance of linked bank accounts. Optional account_name matches the account name, official name, or institution. Optional account_type is checking, savings, credit, investment, loan, or other. One match returns that account; several matches return the list.
get_alerts
ChatGPTReturns today's alerts from FYN's nightly checks of this household's accounts and receipts: possible duplicate charges first, then the rest by importance. Each alert has type (for example duplicate_charge, large_transaction, subscription_price_change, personal_price_change, upcoming_recurring, budget_overrun), severity, title, detail, and date. alert_count covers all of today's alerts; limit defaults to 10 (at most 20). A possible duplicate charge is not confirmed.
get_all_balances
ChatGPTReturns balances for every linked bank account, grouped by account class, plus account_count and total_balance. Credit cards and loans are subtracted.
get_budget_status
ChatGPTReads saved budget allocations against ledger spending for the current budget period. Returns spent_this_month, allocated, comparison_difference, period, period_start, period_end, contributors, review_reasons, allocation_source (autopilot, approved, or automatically_generated), and plan_needs_review. over_budget is true only when one saved allocation is verified and spending exceeds it. over_budget is null when the comparison is unverified (review_reasons is non-empty), including a stale or generated plan, a period mismatch, or a category conflict. An optional category matches one raw key, category id, or display label. Zero or several matches leave spent_this_month, allocated, and over_budget null and set status to category_not_found or ambiguous_category.
get_businesses
ChatGPTReturns each of the household's businesses with income, expenses, net, and transaction count for a date range (default January 1 through today), plus the personal side. A charge counts for a business when it is tagged to that business or posted on its business account; business_not_assigned covers business-account charges with no business named. Transfers and card payments are not counted as income or expenses.
get_cashflow_summary
ChatGPTReturns income, expenses, and net cash flow for a period: this_month (default), last_month, this_year, last_year, or a YYYY-MM or YYYY-MM-DD value. Includes transaction_count and posted purchase counts.
get_categories_over_budget
ChatGPTLists budget categories for the current period. over_budget_categories are those with over_budget true (a verified comparison where spending exceeds the saved allocation). unverified_comparisons are those with over_budget null. Also returns the period and the current-period spending summary.
get_category_rules
ChatGPTLists the categorization rules this household set in FYN, highest priority first: merchant (the text matched), match (exact or contains), category, optional direction and amount range, and learned (true when the rule came from the household correcting a category). Also lists merchant renames (from, to). Up to 200 of each, with rule_count and rename_count. Read-only.
get_cost_of_living
ChatGPTEstimate this household’s spending mix in another US state or metro with BEA 2024 Regional Price Parities. Reports data coverage, category assumptions and exclusions. Area averages, not current quotes, taxes or homeowner-cost estimates.
get_credit_cards
ChatGPTLists linked credit cards: owed, credit_limit, available, utilization_pct, interest_last_12_months (interest charges posted on the card in the last 12 months), and balance_as_of, plus total_owed, total_limit, overall utilization_pct, and total interest. Balances and limits are as the bank last reported them. APR, minimum payment, and due date are not available.
get_grocery_staples
ChatGPTRead recurring food purchases, observed buying cadence and cheapest comparable stores in the household’s own receipts. Does not infer pantry contents, nutrition or allergy safety.
get_holdings
ChatGPTLists investment holdings. Each row includes symbol, quantity, current_value, cost_basis, and gain_loss, plus total_holdings. An empty or unavailable store returns an empty holdings list.
get_merchants
ChatGPTReturns spending per merchant over a date range (default the last 12 months), net of refunds and highest first: name, total, purchases, last_date, main category, and also_seen_as (other store spellings and the household's renames FYN merged under that merchant). Optional query matches any of a merchant's names; limit defaults to 25 (at most 100). merchant_count covers every merchant in the range; unnamed totals charges the bank sent with no merchant name.
get_money_back
ChatGPTLists what the household can still act on from its scanned receipts. kind is price_drop (a lower later price at the same store inside the return window), return_window (a purchase still inside its return window), points (a trip missing a loyalty number seen on earlier receipts), or offer (a survey reward printed on a receipt; its code stays in the FYN app). Each item has merchant, fact, deadline, amount, purchase_date, and the receipt_id of its scanned receipt. deadline is the receipt's printed window, not a store's confirmed policy.
get_net_worth
ChatGPTReturns net worth for linked accounts: assets minus liabilities (net_worth), plus total_assets, total_liabilities, cash, invested, asset_count, and liability_count.
get_net_worth_history
ChatGPTReturns net worth over a period from saved snapshots of linked balances: start, end, change, change_pct, high, low, and up to 60 dated points with net_worth, cash, investments, and (when recorded) assets and liabilities. period is 7d, 30d, 90d (default), 1y, or all. Crypto exchange balances are not in the history.
get_portfolio_summary
ChatGPTReturns linked investment portfolios: portfolio_count, total_value, and each portfolio name, type, exchange, and value. Currency is USD. An empty or unavailable portfolio store returns portfolio_count 0.
get_price_adjustments
ChatGPTLists up to 10 products this household bought whose later receipt at the same store shows a lower price while the purchase receipt's return window is still open. Each row includes product, merchant, you_paid, now_priced_at, reclaimable, return_by, and days_left. Prices come only from this household's receipts. return_by is that return window, not confirmation that the store offers a price adjustment.
get_price_history
ChatGPTRead item price changes and cheapest comparable stores from this household’s own receipt history. Returns observed prices, dates and comparison limits; never live store quotes.
get_receipt_spending
ChatGPTTotals spending from scanned receipts. Optional filters: location (matched against the printed store address; every word must appear), merchant, start_date, and end_date (YYYY-MM-DD). Re-scans of the same meal are collapsed and counted in duplicate_scans_removed. Returns total, receipt_count, by_merchant, and the kept receipts. The total covers scanned receipts only and omits purchases that were not scanned.
get_recent_transactions
ChatGPTReturns transactions newest first. Optional filters: merchant, category, start_date, end_date (YYYY-MM-DD). limit defaults to 10. Each row includes date, merchant, amount, and category, plus receipt line items when a scanned receipt is linked.
get_savings_rate
ChatGPTReturns the savings rate for a period: (income minus expenses) divided by income, as a percent, plus amount_saved, total_income, and total_expenses. The rate is 0 when income is 0. period is this_month (default), last_month, this_year, or last_year.
get_spending_breakdown
ChatGPTReturns spending grouped by merchant or category, with posted purchase counts and average ticket. A posted charge is the visit proxy; refunds reduce net spending and are not purchases. group_by is required. The optional category filter accepts a raw category key or a display label. limit defaults to 5. Omitted dates cover all time. total_spending covers every matching group; breakdown lists the top groups.
get_subscription_total
ChatGPTReturns monthly and yearly totals for recurring charges. monthly_total and subscription_count cover services and memberships (streaming, software, gyms). bills_monthly_total and bill_count cover rent, utilities, childcare, loans, insurance, and other bills. recurring_monthly_total is both. Transfers and card payments are excluded. Charges with an irregular or unknown frequency are listed in not_in_totals and are not included in the monthly or yearly totals.
get_subscriptions
ChatGPTLists active recurring outflows. Each row includes name, amount, frequency, next and last charge, category, and kind (subscription, bill, or transfer), plus status and currency.
get_transaction_sum
ChatGPTSums ledger transactions that match the filters. direction selects the total: expense (default), income, net, credit, or transfer. merchant matches a store name; category matches a spending category or product type. A category total also includes that product bought as line items on scanned receipts at other stores, returned as items_elsewhere and total_with_items. Omitted dates cover the available ledger. Expense totals exclude transfers and income.
get_trip_summary
ChatGPTSummarize observed trips using posted transaction and receipt locations, costs per day and dining tickets compared with home. Missing location evidence is reported; these are past costs, not travel quotes.
get_upcoming_bills
ChatGPTLists bills, subscriptions, and expected income dated within the next days (default 30, at most 90), projected from recurring patterns on linked accounts. Returns bills (name, amount, date, kind, frequency), income, bills_total, income_total, and net. A charge that recurs more than once in the window is listed on each date. Amounts are the latest charge or deposit. Transfers between the household's own accounts and card payments are left out; not_dated lists recurring charges with an irregular cadence.
list_categories
ChatGPTLists the household's active spending categories: FYN's catalog plus categories the household added or renamed. Each row has name, key, parent, type (personal, business, or both), need_or_want (need, want, or other; null for transfer categories), and custom when the household created it. Optional type limits the list to personal or business categories.
search_finances
ChatGPTSemantic search over this household's receipts and transactions. Returns up to 10 relevance-ranked receipts with itemized line items (and a presigned photo URL when the receipt is an image or PDF) and up to 15 matching transactions (merchant, date, amount, category). result_set.ordering is "relevance", result_set.complete is false, and result_set.truncated is true when more matches existed than were returned. The list is not the full ledger and is not ordered by amount or date.
search_receipt_items
ChatGPTReads itemized receipt line items. query matches a product or brand across receipts. merchant with optional start_date and end_date, and with query empty, returns every line item on the matching receipts. A single day uses the same YYYY-MM-DD value for start_date and end_date. At least one of query or merchant is required; otherwise the result is empty.
split_bill
ChatGPTSplits one scanned receipt across people. Inputs are receipt_id, assignments (each person's name and the 0-based indexes of the line items they ordered), and optional shared_item_indexes (items divided evenly across everyone). Returns each person's share with tax and tip allocated in proportion to their items, the line items with indexes, and pre-filled Venmo request links (venmo and venmo_web). payment_links.cashapp is null. Does not send the requests or move money.