Beyond Payday MCP Integration for AI Agents

Returns the current financial summary for the signed-in Beyond Payday account: net worth, total assets, total liabilities, and monthly gross income, take-home income, essential bills, discretionary bills and discretionary income, plus record counts per category. Each figure needs the member's read access to what it is built from, as on the dashboard: income figures need income, bill figures need bills, discretionary income needs both, total assets needs assets, total liabilities needs debts, net worth needs both, and each count needs its own category. Anything the member cannot read is left out, and `not_shown` then says which categories and figures. Figures are monthly, in USD. `discretionary_income` is AFTER TAX — it is take-home minus bills, NOT gross_income minus the bill figures, and subtracting across those two fields produces a number that means nothing. Use `take_home_income` when you need the after-tax income that discretionary_income was built from. These totals EXCLUDE disabled records and business records, and additionally leave out 529 accounts that are unowned or owned by a child. Insurance policies count by cash value only: Term Life and other no-cash-value policies (disability, home, renters, auto, umbrella) are $0, whole, universal, variable universal and indexed universal life count their cash value, and coverage (the death benefit) never counts — so they will not match the sum of the list tools' rows, which include everything. A child account sees only the records assigned to it. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Returns the Beyond Payday account's monthly cash flow — take-home income, essential bills, discretionary bills, and what is left over — plus the bills falling due in the next `days` days. `monthly.take_home_income` is AFTER TAX: Beyond Payday has already applied FICA, pre- and post-tax deductions and 1099 estimated tax, so use it as given and never re-derive a net figure from gross. It is also SIGNED — a business pass-through running at a loss lowers it, and that is real money out, not a zero. `monthly.net_cash_flow` is take-home minus both bill figures. Upcoming due dates are derived from each bill's payment_day, payment_month and frequency: a Monthly bill is due on its payment_day every month, an Annual bill only in its anchor payment_month, and a Bi-Annually bill in its anchor payment_month and again six months later. Days 29–31 clamp to the last day of shorter months. A bill with no payment_day set has no due date to report and is left out of `upcoming_bills` while still counting in the monthly totals. Each upcoming bill is priced for its own due date: a bill on a promotional plan reports the price in effect that day and carries `price_status` — 'unknown' means the household has not confirmed the new price yet, so `amount` is only today's price and must be reported as uncertain, never as final. A bill split with a business reports only the household's share as `amount` and `monthly_amount` (with `full_amount` and `household_share_percent`), since only that share leaves personal accounts, as on the app's Cash flow page. The monthly figures use each bill's current amount, exactly as the dashboard does. These are the amounts the account holder entered; nothing here is a payment and Beyond Payday cannot pay a bill. Needs the Money in and out permission plus income, bills and assets access; a child account has none of it unless the owner grants it, and then sees only the records assigned to it. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Lists recurring bills tracked in the Beyond Payday account, most recently created first, with the amount, how often it is due, its category, and whether it is marked essential. `value_score` is the Save money rating: four optional 0-3 answers (earns, grows, protects, life; null = unanswered), the `value` used to rank what to cut (0 Cut first, 1 Question it, 2 Worth it, 3 Keep; lowest value then highest cost is cut first) , `is_suggestion` when nothing is confirmed yet, and `ranked` (false for a Need: Needs are never rated or ranked for cuts). `amount` is what is due EACH TIME the bill occurs; `monthly_amount` and `annual_amount` are that amount annualized by Beyond Payday's own rule — Monthly ×12; Bi-Annually ×2 (twice per year — NOT every two years); Annual ×1. A bill on a promotional or introductory price also carries `upcoming_price_change` and `ongoing_amount`: `amount` is only what the household pays TODAY, so for any question about the future use `ongoing_amount` (the price once every promotion and finite discount has ended) and say when it changes. A `next_amount` of null means the household has not found out the new price yet — report it as unknown; never treat it as 0 or assume the current price continues. Reads records only; it does not pay anything. A child account sees only bills assigned to it. These rows include DISABLED records and BUSINESS records. beyondpayday_get_overview excludes both from its totals, and additionally leaves out 529 accounts that are unowned or owned by a child and counts policies by cash value only (Term Life and other no-cash-value policies are $0; whole, universal, variable universal and indexed universal life count their cash value; coverage never counts) — so do NOT add these rows up to reproduce an overview figure; call the overview for that. `reviewed_at` is when the figure was last changed or confirmed accurate by the household; `updated_at` also moves on cosmetic edits, so use `reviewed_at` to judge how current a figure is. Paginated: pass limit (1-100, default 25) and offset; the response carries total and nextOffset — keep calling until nextOffset is null before totaling. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Lists income sources tracked in the Beyond Payday account, each with the full per-source breakdown Beyond Payday computes: annual and monthly gross and take-home, itemized deductions (pre- and post-tax, with capped annual amounts and totals; each has the id and linked_asset_id the deduction tools use), the full tax breakdown (income tax and FICA for W2, or estimated income and self-employment tax for 1099/self-employed), supplemental pay (bonus, tips, per-diem, stipends and 401k match), and the effective tax rate. Each source reports the `business_id` it belongs to (null for personal income) and `linked_business_id`, the business a system-generated pass-through profit/loss row belongs to — `business_id` is null on those rows. Filtering by `business_id` matches EITHER field, so a business's pass-through row is included. `salary` is the rate in the unit named by `pay_frequency` (an hourly wage when pay_frequency is "Hourly"), not an annual figure; the annualized gross is `annual_gross`. `annual_take_home` / `monthly_take_home` are each source's contribution to income and cash flow — Beyond Payday's own signed figures with FICA, deductions and 1099 estimated tax already applied. They are NEGATIVE for a business loss / pass-through (`is_pass_through_loss`), which is real money out, not an error and not zero. A child account sees only income assigned to it. These rows include DISABLED records and BUSINESS records. beyondpayday_get_overview excludes both from its totals, and additionally leaves out 529 accounts that are unowned or owned by a child and counts policies by cash value only (Term Life and other no-cash-value policies are $0; whole, universal, variable universal and indexed universal life count their cash value; coverage never counts) — so do NOT add these rows up to reproduce an overview figure; call the overview for that. `reviewed_at` is when the figure was last changed or confirmed accurate by the household; `updated_at` also moves on cosmetic edits, so use `reviewed_at` to judge how current a figure is. Paginated: pass limit (1-100, default 25) and offset; the response carries total and nextOffset — keep calling until nextOffset is null before totaling. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Lists assets tracked in the Beyond Payday account — accounts, property, investments and similar — with their current value, category, institution and owners. Each asset reports the `business_id` it belongs to (null for personal assets), and the list can be filtered to one business with the `business_id` argument. A row Beyond Payday maintains itself (a business-equity asset) carries `derived_from` and `value_last_computed_at`: its value is computed from the business valuation, not entered by the account holder, and it is only as current as that timestamp. A business-equity row may instead carry `value_hidden: true` with `current_value: null`: its value would reveal business debts this member cannot read, so it is withheld and left out of the total_assets of beyondpayday_get_overview — say it is hidden, never estimate it. `excluded_from_overview` marks the rows beyondpayday_get_overview leaves out of its totals. Each row also carries `balance_history` (its last 12 recorded balances, newest first, dated in the household's local time) and `balance_pace` (the least-squares change per month over the last year, or null until at least 3 balances span 90 days). History is read-only here. Insurance assets carry `policy` (coverage details; see below) and investment accounts that can hold holdings carry `holdings_summary` { count, total } — informational only, never added to the asset's value; use beyondpayday_list_holdings for the rows. For an insurance category (Auto/Home/Condo/Renters/Umbrella/Flood/Disability/Long-Term Care Insurance, Term Life and the like) `policy` holds the coverage details. Policies with no cash value (Term Life, Disability Insurance, Homeowners Insurance, Renters Insurance, Auto Insurance, Umbrella Insurance, Flood Insurance, Long-Term Care Insurance, Condo Insurance) keep current_value at 0; for permanent life current_value is the net cash surrender value (after any loan), never the death benefit. The death benefit is policy.coverage_amount and never counts in net worth. A life, disability or long-term care policy covers its owner (family_member_id). Each newer fact applies only to the kinds its description names; a fact the kind cannot carry is not saved (the echo shows null). The premium is never a policy field: a policy bought on your own is paid by a bill; a work policy (employer_provided: true) is paid by a paycheck deduction on the owner's income linked to the asset, so never suggest or create a premium bill for it (the user adds the deduction in the app). Permanent life (Whole, Universal, Variable Universal, Indexed Universal), long-term care and work policies have no end date or term; only Term Life and disability bought on your own end. Home, condo, renters, auto, umbrella and flood policies renew instead (renews_on in reads). Omitted policy fields keep their saved value; on update, policy: null removes the details. The beneficiary note is not available through this connector. Account numbers are not included. A child account sees only assets assigned to it. These rows include DISABLED records and BUSINESS records. beyondpayday_get_overview excludes both from its totals, and additionally leaves out 529 accounts that are unowned or owned by a child and counts policies by cash value only (Term Life and other no-cash-value policies are $0; whole, universal, variable universal and indexed universal life count their cash value; coverage never counts) — so do NOT add these rows up to reproduce an overview figure; call the overview for that. `reviewed_at` is when the figure was last changed or confirmed accurate by the household; `updated_at` also moves on cosmetic edits, so use `reviewed_at` to judge how current a figure is. Paginated: pass limit (1-100, default 25) and offset; the response carries total and nextOffset — keep calling until nextOffset is null before totaling. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Lists debts and liabilities tracked in the Beyond Payday account with their outstanding balance, interest rate, maturity and owners. Each debt reports the `business_id` it belongs to (null for personal debts), and the list can be filtered to one business with the `business_id` argument. A loan whose maturity date has passed is auto-disabled on read, exactly as the app does it, so a paid-off loan does not keep counting. `excluded_from_overview` marks the rows beyondpayday_get_overview leaves out of its totals. A Student Loan reports `student_loan_type` (federal or private); a federal one also reports its repayment plan and Public Service Loan Forgiveness progress (`pslf_progress`, e.g. "48 of 120 qualifying payments"; never estimate forgiveness beyond that count). Each row also carries `balance_history` (its last 12 recorded balances, newest first, dated in the household's local time) and `balance_pace` (the least-squares change per month over the last year, or null until at least 3 balances span 90 days). History is read-only here. Account numbers are not included. A child account sees only debts assigned to it. These rows include DISABLED records and BUSINESS records. beyondpayday_get_overview excludes both from its totals, and additionally leaves out 529 accounts that are unowned or owned by a child and counts policies by cash value only (Term Life and other no-cash-value policies are $0; whole, universal, variable universal and indexed universal life count their cash value; coverage never counts) — so do NOT add these rows up to reproduce an overview figure; call the overview for that. `reviewed_at` is when the figure was last changed or confirmed accurate by the household; `updated_at` also moves on cosmetic edits, so use `reviewed_at` to judge how current a figure is. Paginated: pass limit (1-100, default 25) and offset; the response carries total and nextOffset — keep calling until nextOffset is null before totaling. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Lists the savings and debt-payoff goals tracked in the Beyond Payday account. Fields per goal: `target_amount`, the figure the account holder is aiming at; `target_date`, the date they set. `current_amount` MEANS DIFFERENT THINGS BY GOAL TYPE — for a savings goal (`asset_id` set) it is the linked asset's current balance; for a payoff goal (`liability_id` set) it is the REMAINING DEBT BALANCE, not an amount saved. `total_saved` is the progress so far: for a linked goal, how far the linked balance has moved from `start_balance` (up for savings, down for a payoff goal); for an unlinked goal, the sum of the contributions logged against it. `remaining_amount` is what is still to go. `progress_percent` is a percentage on a 0-100 scale, not a fraction. `contribution_amount` with `contribution_frequency` is the schedule the account holder entered, and `expected_contribution` is what that schedule implies by now. `health` and `health_reason` are Beyond Payday's own on-track assessment, phrased as a note to the account holder; `assessment_basis` says what it was derived from. `time_remaining` is a human-readable span to the target date. `breakdown` (read-only, may be null) lists the pieces the account holder split the target into in the app, as `{label, amount}`; the amounts add up to `target_amount`. It cannot be edited through this connector. `real_pace` (active linked goals only; may be absent) is the pace from the linked record's real balance history over the last year, not the planned contribution: `monthly_change` (per month, negative = falling; null until at least 3 balances over 90+ days exist), `reach_date` (YYYY-MM-DD the target is reached at that pace; null when unproven, moving the wrong way, or over 50 years out) and `points_needed` (past balances still needed before a pace can be shown). `linked_not_shared: true` means the goal is linked to an account or debt this account holder is not allowed to see: its balance-derived fields (`current_amount`, `total_saved`, `remaining_amount`, `progress_percent`, `health`, `health_reason`, `real_pace` and the rest) are null — say the linked account is not shared with them; never guess or estimate them. A child account sees only goals attached to a record assigned to it. Paginated: pass limit (1-100, default 25) and offset; the response carries total and nextOffset — keep calling until nextOffset is null before totaling. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Lists the businesses tracked in the Beyond Payday account with their entity type, industry, estimated tax rate and valuation settings. A business's own income, assets and debts are available from beyondpayday_list_income, beyondpayday_list_assets and beyondpayday_list_debts filtered by business_id, and its expenses from beyondpayday_list_business_expenses. Requires a Beyond Payday plan that includes businesses. Employer identification numbers are never returned, and a child account sees only the businesses it is a listed owner of. Paginated: pass limit (1-100, default 25) and offset; the response carries total and nextOffset — keep calling until nextOffset is null before totaling. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Lists the expenses of one business — the bills that belong to it — most costly first by annual cost to the business. Only ENABLED bills are included. Each entry has the bill's payee, category and how often it recurs, the FULL bill amount for one occurrence (in that frequency, matching beyondpayday_list_bills), the `percentage` of the bill that belongs to this business, and `business_amount`, the business's share of one occurrence. `annual_amount` and `annual_business_amount` are the same two figures annualized: Monthly ×12; Bi-Annually ×2 (twice per year — NOT every two years); Annual ×1. A bill assigned directly to the business (rather than split by a percentage) appears at `percentage: 100`. These are CURRENT prices, as the Business Overview uses; a bill on a promotional plan also carries `upcoming_price_change` and `ongoing_amount` for the whole bill (apply `percentage` for the business share) — use those for any question about the future. Requires a Beyond Payday plan that includes businesses. Reads records only; it does not pay anything. A child account can list expenses only for a business it co-owns. Paginated: pass limit (1-100, default 25) and offset; the response carries total and nextOffset — keep calling until nextOffset is null before totaling. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Returns one business's financial picture: annual revenue, annual expenses, annual and monthly profit, the current value of the assets and debts on its own books, and its valuation. A balance total the member has no access to (assets or debts) is left out, along with net assets and any valuation built from them (every method but manual); `not_shown` then says which. All figures are ANNUAL and FORWARD-LOOKING — Beyond Payday annualizes the recurring income and bills on the books right now; they are not last year's actuals and not a tax filing. Revenue is the enabled income rows assigned to the business; expenses are the bills allocated to it (see beyondpayday_list_business_expenses for the itemized list). Profit is revenue minus expenses and is NEGATIVE for a business running at a loss — report the loss, never floor it at zero. `valuation` is computed from the business's own `valuation_method` and `valuation_multiplier`, which the account holder chose; it is a modelling assumption, not a market price or an appraisal, so say so rather than quoting it as what the business is worth. Requires a Beyond Payday plan that includes businesses. Employer identification numbers are never returned, and a child account cannot use this. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Lists the saved what-if scenarios in the Beyond Payday account — named sets of income and bill changes the account holder modelled — with the number of additions and removals in each and any stacked life changes (e.g. Buy a car, Moving). Read one in full with beyondpayday_get_scenario; create, change or delete with beyondpayday_create_scenario / beyondpayday_update_scenario / beyondpayday_delete_scenario. Only the family owner or spouse can read scenarios, with What-if planner, income, bills and assets access. Paginated: pass limit (1-100, default 25) and offset; the response carries total and nextOffset — keep calling until nextOffset is null before totaling. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Returns one saved what-if scenario as the What-if page shows it: each stacked life change (change_id, paused) with its rows — the user's related items, each with its row key, today's amount, the choices it allows and its current one (Keep / Remove / Sell / Trade in / Pay off / Replace and the replacement amount), or changed_by when another change already changes that item — its "Also add?" chips, new items, and its purchase (price, down payment, rate, term, closing costs, the accounts paying and their amounts, loans); "Something else" (items taken out by hand, items added by hand, older purchases); and totals: money left over, bills (monthly) and net worth before → after, computed by Beyond Payday with the page's own math — report them, never recompute them. Use the ids and keys with beyondpayday_update_scenario and pass updated_at as expected_updated_at. Only the family owner or spouse can read it, with What-if planner, income, bills and assets access. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Returns the saved dashboard snapshots for the Beyond Payday account, newest first — each one a dated record of net worth, total assets, total liabilities and the monthly income and bill figures at that time. Snapshots exist only for dates one was saved (by the account holder, or automatically — `source: auto` — about a day after balances were updated, at most one a month); this does not reconstruct history. An automatic snapshot has `recomputed_at` when a later fix to a past balance updated its totals, and `stale_balances` counts the balances in it not checked in a while. Totals this person may not see (no Debts access; or no Assets access, for total assets and net worth) are null and named in `hidden_totals` — never estimate them. When the returned snapshots span the day permanent life insurance cash value started counting in net worth, a top-level `notes` list explains the step; repeat it when comparing across that day. For current figures use beyondpayday_get_overview. A child account receives an empty list. Paginated: pass limit (1-100, default 25) and offset; the response carries total and nextOffset — keep calling until nextOffset is null before totaling. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Returns the household's saved SHTF (hard-times) plan: the actions it would take if income stopped — selling or withdrawing from assets, cutting or replacing bills, housing changes — grouped by severity level, with the plan's start date and settings. Each change in `plan.actions` has an `id`, a `fromLevel` and base `settings`; `plan.levels[n].overrides[id]` holds what level n changed (a change made at one level carries into every more severe level, unless that level holds its own value; a change added at one level is listed unchecked at milder levels). Unchecked changes (`enabled: false`) are included. `changes_by_level` is the same plan resolved per level, as the page shows it: every change available at that level with `checked`, `editedHere` (changed for this plan in more than checked or unchecked; use_lower_level_choice resets it) and all its fields flat under the plan's own names (`amount`, `startMonth`, `sale.salePrice`, `withdrawal.taxAmount`, …); `netCash` for a sale or withdrawal is computed by Beyond Payday with the page's rules — report it, never recompute it. A sale has no `amount` of its own. Bill and asset references are ids from beyondpayday_list_bills / beyondpayday_list_assets; an id that no longer resolves means that record was deleted after the plan was saved. `saved` is false when the household has not saved a plan yet: `plan` is then the starting plan the SHTF page shows (built from their bills), and the first edit saves it. Change it with beyondpayday_update_shtf_plan, using these ids. Coverage isn't computed here; the SHTF page's verdict and Covered here marker show it. The plan is the household's own hypothetical scenario, not a recommendation. Only the family owner or spouse can read it, and only with SHTF plan, income, bills and assets access. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Lists the bills Beyond Payday's Save money page offers tips for, each with the tip set (`playbook`) matched to it: its label, a one-line summary and the tip titles. `source` says how the match was made — 'user' (the household chose it), 'rule' (a confident keyword match), 'ai' (saved AI match) or 'fallback' (the category's general tips). The tips are general, hand-written suggestions, not advice about this household's providers or contracts. Needs the Save money permission and bills access; a child account has neither unless the owner grants it, and then sees only bills assigned to it. For each bill's full details use beyondpayday_list_bills; to change a bill use beyondpayday_update_bill. Paginated: pass limit (1-100, default 25) and offset; the response carries total and nextOffset — keep calling until nextOffset is null before totaling. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Returns who this connection is acting as: the signed-in person's display name, their role in the family (owner, spouse or child), the family name, their timezone, and the list of family members by name and relationship. Email addresses and birthdays are never included. Call it to learn whose data this connection can see; for financial figures use beyondpayday_get_overview.

Lists the investments inside one account (symbol, name, kind, shares, price, value, cost basis) with the app's own summary: the total, the split by kind as percentages, the unrealized gain when cost basis is known, and whether the holdings total differs from the account's value (summary.mismatch; for an HSA the cash balance outside the holdings is expected, returned as summary.mismatch.cashNotInHoldings, never a mismatch to fix). Holdings are informational: they never change the account's value or net worth. The account's own current_value stays what the user entered; use beyondpayday_update_asset to change it. Only investment accounts can hold holdings (up to 500 each). Get the asset id from beyondpayday_list_assets. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Lists the stock option, RSU, PSU and ESPP grants behind one stock compensation asset, each with its vesting schedule and figures as of today, plus `summary`: the app's own totals (vestedValue leaves out double-trigger grants, which are in waitingForSaleValue; unvestedValue; missingValueCount; the next vest). Grants are informational: they never change the asset's value or net worth. Beyond Payday works out the figures (before tax) from the vesting schedule: vested_shares, held_shares (vested minus shares no longer held), vested_value (the held shares' value, "Vested, not yet sold"), unvested_shares, unvested_value and next_vest {date, shares}. An ESPP row is a purchase: every share is owned right away. Values are null when no share price is set. An option past its expires_on date has expired: expired is true, its values are 0 and it is left out of the totals. Ask the user for every date, share count and price; never fill one in. Get the asset id from beyondpayday_list_assets. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Returns the household's saved tax facts (filing status, state and state tax rate, children and other dependents as counts, standard or itemized deduction, other taxable income not on the Income page, pre-tax savings outside payroll) or null when none are saved. When Beyond Payday's tax estimate is switched on for this user it also returns `estimate` (federal and state tax, self-employment tax, effective and marginal rate, the steps, and what it does not cover) once facts are saved; otherwise `estimate_available` is false and there is no estimate. It also returns counted_from_income_page: the Income page rows the estimate already counts (name, type, how each is taxed, yearly amount, a note); never add those again to other_taxable_income, which is only for taxable income NOT on the Income page. non_taxable_income is what the estimate leaves out as not taxed. Business profit is taxed by the business type: sole proprietorship, LLC and partnership profit gets self-employment tax; S-corporation profit (including an LLC taxed as one) is taxed as income with no self-employment tax; C-corporation profit is left out because the business pays its tax (salary or dividends it pays are their own income rows). family_defaults (filing status and dependent counts suggested from the family members, by age at year end from a birthday or birth year) are what the app pre-fills when no tax facts are saved; a child with no birthday or birth year is not counted and childrenWithoutBirthDate says how many, so ask about them: offer them as a starting point and ask the user to confirm before saving any. These are the household's own entries, not tax advice. Dependents are counts only — never names or birthdays. Beyond Payday works out any estimate itself; never compute taxes from these facts. Needs permission to read income. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Compares the household's saved insurance policies (life, disability, home, condo, renters, auto, umbrella, flood and long-term care) with common rules of thumb. Each item has a status: below_rule_of_thumb or at_or_above_rule_of_thumb (compared with the rule), info (information only, nothing to compare: the home dwelling, condo walls-in, flood and long-term care coverage, or a policy for someone with no income to replace), missing (none entered), not_enough_info (needs more details) or review_due (time to review it, including "Did this renew?" when a renewal date has passed). It is a comparison of the user's own numbers, NOT insurance advice: never tell the user a policy is good, enough or inadequate, and never recommend buying, changing or cancelling coverage. Each item carries its own plain wording and the rule of thumb it used; repeat those, do not paraphrase them into advice. Needs permission to read assets, income and debts. Not available yet until Beyond Payday turns it on: it then returns available: false. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Shows what one person's own Social Security retirement benefit would be if claimed at each age from 62 to 70, the total received through chosen later ages, and the age each choice catches up with claiming at full retirement age. It starts from the benefit amount saved in Retirement settings and the birth year. monthly_benefit is the "Monthly benefit (before Medicare)": Medicare Part B is usually taken out of the check. Ages the person has already passed are left out, and already_started is true when a Social Security Retirement or Disability (SSDI) income for them is already on the Income page (the claiming age was already chosen, or SSDI turns into retirement benefits at full retirement age). With no benefit of their own saved, has_benefit_amount is false and, when the partner has one, spousal_benefit_at_full_retirement_age_up_to gives up to half the partner's full-retirement-age benefit. When their own benefit is under half the partner's, spousal_top_up_at_full_retirement_age_up_to is the most they could get on top as a spouse, once the partner has started. Survivor benefits and the full spousal rules are not compared (see not_compared_yet). Amounts are today's dollars with no cost-of-living changes. It is a comparison, NOT a recommendation: never tell the user when to claim. Needs permission to read Retirement and Family. Not available yet until Beyond Payday turns it on: it then returns available: false. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Records a new recurring bill in the Beyond Payday account so it counts toward the budget. Pass business_allocations to mark it as a business expense split across one or more businesses. Do not use it for a credit card's payment: a card paid in full has no payment bill, and a card that carries a balance is paid down by its extra payment (beyondpayday_update_debt card_extra_payment). This only creates a record — Beyond Payday does not move money and cannot pay a bill. To change an existing bill, use beyondpayday_update_bill instead. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Changes fields on an existing Beyond Payday bill record. Only the fields provided are changed; everything else is left as it is. value_earns/value_grows/value_protects/value_life set the Save money value answers (0-3). Passing business_allocations replaces the bill's business-expense split. This edits a record and does not move money. Get the id from beyondpayday_list_bills. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Permanently deletes a bill record from the Beyond Payday account, along with its links to assets and businesses. This cannot be undone, and it does not cancel anything with the biller. To keep the bill but leave it out of totals, set enabled: false with beyondpayday_update_bill instead. Get the id from beyondpayday_list_bills. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Records a new income source in the Beyond Payday account so it counts toward budget and take-home calculations. Supplemental pay such as bonuses, tips, per diem and 401(k) match must be added in the Beyond Payday app; this tool does not set them. Add paycheck deductions afterwards with beyondpayday_create_income_deduction. The result carries the saved record with Beyond Payday's own computed figures — annual_gross, annual_take_home, monthly_take_home and the full tax breakdown — so use those rather than annualizing `salary`, which is a RATE in the unit named by pay_frequency. To change an existing income source, use beyondpayday_update_income instead. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Changes fields on an existing Beyond Payday income record. Only the fields provided are changed. Supplemental pay is not editable through this tool; the user adds it in the app. Paycheck deductions (401(k), HSA, premiums, an ESPP contribution) have their own tools: beyondpayday_create_income_deduction, beyondpayday_update_income_deduction and beyondpayday_delete_income_deduction. The result carries the recomputed annual_gross, annual_take_home and monthly_take_home for the saved record; use those rather than recalculating from `salary`. Get the id from beyondpayday_list_income. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Permanently deletes an income record from the Beyond Payday account, along with its payroll deductions. This cannot be undone. To keep the income source but leave it out of totals, set enabled: false with beyondpayday_update_income instead. Get the id from beyondpayday_list_income. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Adds one deduction to a paycheck. A paycheck deduction is money taken out of one paycheck before it reaches the bank: retirement (401k, 403b, 457, TSP, SIMPLE IRA, pension), HSA and FSA, health, dental and vision premiums, union dues, and similar. A work insurance premium (life, disability, accident) and an ESPP contribution are paycheck deductions linked to their asset with linked_asset_id (the policy or the ESPP stock asset), not bills. Amounts are per paycheck. The result carries the paycheck with Beyond Payday's recomputed take-home (income.annual_take_home, income.monthly_take_home); use those rather than recalculating. To change an existing paycheck deduction, use beyondpayday_update_income_deduction instead. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Changes fields on one paycheck deduction (ids are in each source's deductions in beyondpayday_list_income). Only the fields provided are changed. A paycheck deduction is money taken out of one paycheck before it reaches the bank: retirement (401k, 403b, 457, TSP, SIMPLE IRA, pension), HSA and FSA, health, dental and vision premiums, union dues, and similar. A work insurance premium (life, disability, accident) and an ESPP contribution are paycheck deductions linked to their asset with linked_asset_id (the policy or the ESPP stock asset), not bills. Amounts are per paycheck. The result carries the paycheck with Beyond Payday's recomputed take-home (income.annual_take_home, income.monthly_take_home); use those rather than recalculating. Get the id from beyondpayday_list_income. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Permanently deletes one paycheck deduction; take-home goes up by what it took. The paycheck itself and any linked account are kept. Get the id from beyondpayday_list_income. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Records a new asset — an account, property, vehicle or investment — in the Beyond Payday account so it counts toward net worth. This creates a record only; it does not open or fund anything. To change an existing asset, use beyondpayday_update_asset instead. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Changes fields on an existing Beyond Payday asset record, such as its current value. Only the fields provided are changed. Changing the category of an investment account to one that cannot hold holdings, or of a stock-compensation account to one that cannot hold grants, permanently removes those holdings or grants; say so before doing it. This edits a record and does not move money. Get the id from beyondpayday_list_assets. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Permanently deletes an asset record from the Beyond Payday account. This cannot be undone, and it does not close any real account. To keep the asset but leave it out of totals, set enabled: false with beyondpayday_update_asset instead. Get the id from beyondpayday_list_assets. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Adds one investment (for example a fund or stock) to an investment account. Holdings are informational: they never change the account's value or net worth. The account's own current_value stays what the user entered; use beyondpayday_update_asset to change it. Only investment accounts can hold holdings (up to 500 each). This records what the user tells you and buys nothing. To change an existing holding, use beyondpayday_update_holding instead. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Changes fields on one holding. Only the fields provided are changed. Holdings are informational: they never change the account's value or net worth. The account's own current_value stays what the user entered; use beyondpayday_update_asset to change it. Only investment accounts can hold holdings (up to 500 each). Get the id from beyondpayday_list_holdings. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Permanently deletes one holding record. This cannot be undone and does not sell anything. It does not change the account's value. Get the id from beyondpayday_list_holdings. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Adds one stock option, RSU, PSU or ESPP grant to a stock compensation asset. Grants are informational: they never change the asset's value or net worth. Beyond Payday works out the figures (before tax) from the vesting schedule: vested_shares, held_shares (vested minus shares no longer held), vested_value (the held shares' value, "Vested, not yet sold"), unvested_shares, unvested_value and next_vest {date, shares}. An ESPP row is a purchase: every share is owned right away. Values are null when no share price is set. An option past its expires_on date has expired: expired is true, its values are 0 and it is left out of the totals. Ask the user for every date, share count and price; never fill one in. This records what the user tells you; it grants, exercises and sells nothing. To change an existing stock grant, use beyondpayday_update_equity_grant instead. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Changes fields on one stock grant. Only the fields provided are changed. Grants are informational: they never change the asset's value or net worth. Beyond Payday works out the figures (before tax) from the vesting schedule: vested_shares, held_shares (vested minus shares no longer held), vested_value (the held shares' value, "Vested, not yet sold"), unvested_shares, unvested_value and next_vest {date, shares}. An ESPP row is a purchase: every share is owned right away. Values are null when no share price is set. An option past its expires_on date has expired: expired is true, its values are 0 and it is left out of the totals. Ask the user for every date, share count and price; never fill one in. Get the id from beyondpayday_list_equity_grants. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Permanently deletes one stock grant record. This cannot be undone and exercises or sells nothing. It does not change the asset's value. Get the id from beyondpayday_list_equity_grants. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Changes the household's saved tax facts. Only the fields provided are changed; with no profile saved yet it creates one and then needs filing_status. Ask the user for every value they did not give — never guess a filing status, a state rate or a dependent count. If deduction_choice is itemized, itemized_total is required. These are the household's own entries, not tax advice. Dependents are counts only — never names or birthdays. Beyond Payday works out any estimate itself; never compute taxes from these facts. This edits a record; it files nothing. Get the current facts from beyondpayday_get_tax_profile (its profile.updated_at can be sent as expected_updated_at). Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Records a new debt or liability in the Beyond Payday account so it counts against net worth. This creates a record only; it does not borrow, pay down, or transfer anything. To change an existing debt, use beyondpayday_update_debt instead. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Changes fields on an existing Beyond Payday debt record, such as its outstanding balance. Only the fields provided are changed. This edits a record and does not move money. Get the id from beyondpayday_list_debts. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Permanently deletes a debt record from the Beyond Payday account. This cannot be undone, and it does not settle or close the real obligation. To keep the debt but leave it out of totals, set enabled: false with beyondpayday_update_debt instead. Get the id from beyondpayday_list_debts. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Records a new savings or debt-payoff goal in the Beyond Payday account. Link it to a real account with asset_id or to a real debt with liability_id and Beyond Payday tracks progress from that record's live balance; leave both unset for a goal tracked only by logged contributions. `current_amount` is NOT a field you set — Beyond Payday derives it, and it means different things by goal type. With `asset_id` set (a savings goal) it is that account's live balance; with `liability_id` set (a payoff goal) it is the REMAINING DEBT balance, which counts DOWN toward the target. `start_balance` is the starting point the progress is measured from — for a payoff goal that is the balance owed on day one, not an amount saved. Ask the user for anything you do not already know — the target figure, the date and which account or debt it tracks — rather than assuming. This only creates a record; Beyond Payday does not move money. To change an existing goal, use beyondpayday_update_goal instead. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Changes fields on an existing Beyond Payday goal record. Only the fields provided are changed; everything else is left as it is. `current_amount` is NOT a field you set — Beyond Payday derives it, and it means different things by goal type. With `asset_id` set (a savings goal) it is that account's live balance; with `liability_id` set (a payoff goal) it is the REMAINING DEBT balance, which counts DOWN toward the target. `start_balance` is the starting point the progress is measured from — for a payoff goal that is the balance owed on day one, not an amount saved. Changing asset_id or liability_id re-points which record the progress is read from. This edits a record and does not move money. Get the id from beyondpayday_list_goals. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Permanently deletes a goal record from the Beyond Payday account, along with the contributions logged against it. The account or debt the goal tracked is NOT deleted and its balance is unchanged. This cannot be undone. Get the id from beyondpayday_list_goals. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Records a contribution against a Beyond Payday goal and returns the goal with its progress recalculated. Use this only for a goal tracked by logged contributions. It is rejected for a goal LINKED to an account (asset_id) or a debt (liability_id): that goal already follows the record's live balance, so a logged contribution would double-count — update the account with beyondpayday_update_asset, or the debt with beyondpayday_update_debt, instead. Contributions are append-only: to correct one, log the negative of it. This records that money moved; it does not move any. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Records a new business in the Beyond Payday account, along with the business-equity asset that carries its valuation into the household's net worth and, for the owners, the pass-through income rows its profit flows through. Requires a Beyond Payday plan that includes businesses. Employer identification numbers cannot be set through a connector — the account holder enters an EIN in the app. Do NOT guess or infer any value here. Ask the user for anything you were not told — especially the entity type, the valuation method and multiplier, and the estimated tax rate, each of which changes the figures Beyond Payday reports for the whole household. Read the amounts back to the user and have them confirm before writing. This creates records; it does not register, form, or file anything for a business. To change an existing business, use beyondpayday_update_business instead. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Changes fields on an existing Beyond Payday business record. Only the fields provided are changed; everything else is left as it is. Changing the name or the entity type rewrites the owners' pass-through income rows, and changing the valuation settings moves the household's net worth — so neither is a cosmetic edit. Employer identification numbers cannot be set through a connector. Do NOT guess or infer any value here. Ask the user for anything you were not told — especially the entity type, the valuation method and multiplier, and the estimated tax rate, each of which changes the figures Beyond Payday reports for the whole household. Read the amounts back to the user and have them confirm before writing. This edits records and does not file anything. Get the id from beyondpayday_list_businesses. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Changes the household's SHTF (hard-times) plan the way the SHTF page does: starting numbers, each level's income/recovery/price assumptions, checking or unchecking a change per level, editing its fields, using the lower-level choice, and adding or removing changes of every kind — bill cuts, benefits, extra income, crowdfunding and one-time cash, moving in with family or friends or to cheaper housing, selling a vehicle, home or other asset, withdrawing retirement or investment money, and a bankruptcy estimate. Call beyondpayday_get_shtf_plan first and use its change ids and field names (the plan's own), and pass its updated_at as expected_updated_at (null when saved=false); bill and asset ids come from beyondpayday_list_bills / beyondpayday_list_assets. The plan is hypothetical: nothing in the household is cancelled, sold or changed. Figures such as sale proceeds, net cash after taxes and a tax estimate from a rate are computed by Beyond Payday with the page's own rules; never compute or invent them, and never fill in an amount, month, tax, penalty, benefit or price the user did not give you — ask. A sale's price and loan payoff start from the recorded value and linked debts, as on the page; a vehicle or other non-real-estate sale also stops the payment bill of the loan it pays off unless you send its bill list, and a home or property sale stops no bill until the user says which. Only the family owner or spouse can change it, and only with SHTF plan update plus income, bills and assets access. Returns the saved plan and what changed. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Creates a what-if scenario on the What-if planner page, optionally starting from a life change (new_job (New job), raise (Get a raise), part_time (Go part-time), lose_job (Lose a job), moving (Moving), downsize (Downsize), buy_home (Buy a home), buy_car (Buy a car), sell_car (Sell a car), baby (Have a baby), side_hustle (Side hustle), pay_off_debt (Pay off a debt), cut_costs (Cut costs)) filled in the way the page's form does for their own data. Change it afterwards with beyondpayday_update_scenario. Never fill in an amount, price, rate or account the user did not give you — ask; the only defaults are the page's own pre-fills. Only the family owner or spouse can do this, with What-if planner update plus income, bills and assets access. Returns the new scenario as the page shows it. To change an existing scenario, use beyondpayday_update_scenario instead. Hypothetical scenario only: no bill, income, account or asset in the household was changed. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Changes a saved what-if scenario the way the What-if page does: rename it; stack a life change and fill in its form; edit a change's form (each related item's Keep / Remove / Sell / Trade in / Pay off / Replace and its amount, "Also add?" chips, new items, the purchase's price, down payment, rate, term, closing costs, which accounts pay and what is borrowed); pause, resume or remove a change; and "Something else" hand edits (take a real item out, put it back, add, edit or remove a hypothetical item, edit or remove an older purchase). Call beyondpayday_get_scenario first and use its change ids, row keys and names, and pass its updated_at as expected_updated_at. A row "changed_by" another change can only be changed there. Names that match several things come back with the candidates (a candidates list of id and label) — ask which one. A refusal that names a row says [name_1] and gives the text in names. Never compute figures or fill in an amount, price, rate or account the user did not give — ask. Only the family owner or spouse can do this, with What-if planner update plus income, bills and assets access. Returns the saved scenario and what changed. Hypothetical scenario only: no bill, income, account or asset in the household was changed. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

Permanently deletes a saved what-if scenario (the household's real data is untouched). Get the id from beyondpayday_list_scenarios. Pass the scenario's updated_at as expected_updated_at so a scenario changed since is not deleted. Only the family owner or spouse can do this, with What-if planner update plus income, bills and assets access. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.