Polaris User Guide

1. Welcome to Polaris

Polaris (listed as Polaris Cash Flow on the App Store and Google Play, package com.polarischashflow.app) answers one question: will my checking account still be in the black three months from now? It projects a rolling 90-day cash flow forecast from your real balances, your recurring income and bills, and your credit card due dates — so a bill that's easy to forget on paper shows up on the chart weeks in advance.

It's built for individuals and households managing shared finances together, available on iOS and Android, with a free tier and three paid tiers (Basic, Pro, Elite) that add bank syncing, statement import, an AI assistant, and more.

This guide covers every feature, what's free vs. paid, and how to use and configure each part of the app.

2. Before You Download

Is Polaris free?

Yes. The Free tier is fully usable with no trial or expiration — unlimited manual accounts, transactions, recurring items, the 90-day projection, Insights, household sharing, and notifications. Paid tiers (Basic, Pro, Elite) add bank syncing, statement import, the AI assistant, and remove ads (see Free vs. Paid Plans below). There's no feature that stops working after a trial period — what you see on Free is yours to keep using indefinitely.

How do I install it? Where do I download it?

• Android: Google Play — "Polaris Cash Flow"
• iOS: App Store — "Polaris Cash Flow" (requires iOS 16.4 or later)

There is no desktop or web app — Polaris is mobile-only (iOS and Android), with your data synced in real time between your own devices if you sign in on more than one.

How does Polaris help me with my budget?

Polaris isn't a traditional envelope/category-budgeting app — it doesn't set spending limits or savings goals per category. Instead, it helps you budget by forecasting: it projects your checking balance 90 days out from your real accounts, recurring bills, income, and credit card due dates, so you see a cash crunch coming weeks in advance instead of finding out when a payment bounces. The Insights tab adds a monthly income/expense/investment breakdown so you can see where money is actually going, and (Pro/Elite) What-If scenarios let you test a purchase's impact before you make it. Think of it as "will I have enough, and when" rather than "did I stay under my grocery limit this month."

Does Polaris move my money or pay my bills?

No. Polaris is read-only/tracking — it never initiates a payment or transfer. Bank connections (Plaid) only pull balances and transactions for forecasting; you still pay bills through your bank or card issuer as usual.

Is my financial data safe?

Bank logins are entered directly in Plaid's own secured flow, never typed into Polaris. You can lock the app behind Face ID/Touch ID or a password (auto-locking after 15 minutes of inactivity if biometrics are off), and block screenshots from Settings. See Privacy Policy in Settings for the full data-handling details.

3. Getting Started

1. Create your account with email and password, then verify your email address (a verification screen blocks entry until this is done).
2. Complete the Setup Wizard when prompted — or skip it and configure things later from Settings.
3. Add at least one account: Accounts tab → Add for a manual account, or Accounts tab → Connect to link a real bank via Plaid (Basic/Pro/Elite only).
4. Add recurring income and expenses from the Recurring list so the forecast has something to project.
5. Open the Dashboard to see your projected cash flow.

Signing up and first launch

Sign up with email and password, then verify your email — a verification screen blocks entry until you do (resend the link if needed). First launch shows a skippable 3-slide intro:

1. "Your Financial North Star" — track all your accounts in one place.
2. "See Your Future Balance" — 90-day projections from your recurring income and expenses.
3. "Built for Households" — share finances with family, synced in real time.

Then the Setup Wizard (also skippable, and re-runnable later) walks you through: add your first account → add one recurring item → "You're All Set!" → go to Dashboard.

The main screens

• Dashboard – balance summary, 90-day projection chart, event timeline, and What-If scenarios (Pro/Elite).
• Insights – monthly income, expenses, and investments broken out, both from actual transactions and from forecasted recurring events.
• Accounts – your account list, bank connect/reconnect, add/edit accounts.
• Assistant – the AI chat assistant (only shown once enabled, and requires Pro or Elite).
• Settings (gear/menu icon) – profile, preferences, subscription, AI assistant, household sharing, legal, and account actions.

4. Accounts

Polaris tracks three account types: Checking, Savings, and Credit Card.

Add an account manually (all plans)

1. Accounts → Add.
2. Choose the account type, enter a name, institution, and current balance.
3. For credit cards, optionally add: statement closing day, due day, and credit limit — these drive the credit card payment projections and the card recommendation feature (see Projections).

Connect a real bank account (Plaid — Basic/Pro/Elite)

1. Accounts → Connect.
2. Complete the Plaid link flow with your bank login.
3. Select which of that bank's accounts to import.

Connection limits: Basic does not include bank connections at all; Pro includes up to 2 connected accounts; Elite is unlimited. Balances and transactions on connected accounts sync automatically — you don't enter them by hand.

Plaid covers thousands of US banks and credit unions. After linking an institution you pick exactly which of its accounts to import (a bank may expose several; you don't have to import all of them) — handled by its own screen in the connect flow. Balances and new transactions then sync automatically in the background; you don't manually refresh them.

Reconnect a broken bank connection

If Plaid's link to your bank breaks (expired credentials, bank-side changes), Polaris shows a reconnect banner on Accounts or Account Details, and separately sends you a push notification and email the moment it happens (regardless of your notification settings) so you find out immediately rather than next time you open the app. Tap the banner or the notification to run the Plaid reconnect flow again.

Editing and deleting

Any editor can edit account details. Only the account owner can delete an account — shared household members with editor or viewer roles cannot delete an owner's accounts.

Currency

New accounts are created in USD. Settings → Preferences → Default Currency lets you pick USD, EUR, GBP, or BRL as your overall display preference, ready for when per-account currency selection is added.

5. Transactions

Manual entry and editing

From Account Details, open or add a transaction to set its description, amount, date, category, and notes. Transactions can be linked or unlinked to a recurring item so the projection engine knows an expected event already happened.

Categories

Transactions can be tagged with a category: Salary, Freelance, Investment, Other Income, Food & Dining, Groceries, Transportation, Shopping, Bills & Utilities, Entertainment, Healthcare, Housing, Savings & Investments, or Uncategorized. Typing a description runs it against a rule-based matcher (e.g. "Starbucks" → Food & Dining, "Netflix" → Entertainment, "rent"/"mortgage" → Housing) that suggests a category automatically; you can always override it. Manage your own custom categories from Settings → Categories.

Default categories are marked SYSTEM and can't be deleted; any default already used on a transaction is also marked IN USE. You can add your own custom categories from Settings → Categories, each with its own type (income/expense/both), icon, and color.

Each transaction also carries a source tag: manual, csv, pdf (statement import), plaid (bank sync), agent (created via the external Agent API), so you can always tell how a transaction got there.

Explain This Transaction (Pro, Elite — requires AI Assistant enabled)

On a transaction's detail screen, an Explain action asks your configured AI provider (your own key, or Polaris's built-in Gemini model on Elite) to identify the likely merchant and summarize what the charge probably is — useful for cryptic statement descriptors. It includes a confidence level (high/medium/low), the reasoning, a caution note when appropriate, and helpful links. It also recognizes known merchant rebrand/alias patterns (e.g. a statement descriptor for the legal entity behind a consumer brand) that a plain category rule would miss.

Import a PDF bank statement (Basic, Pro, Elite)

1. Open an account → Import Statement.
2. Select a PDF file (text-based, under 10MB works best).
3. Review the parsed transactions on Review Transactions.
4. Confirm to import — duplicates against existing transactions are detected automatically.

If parsing returns nothing, try a different statement export from your bank's portal. This is Free-tier-excluded; Basic and above can import statements.

6. Recurring Items

Recurring items are what give the projection its power — anything that happens on a predictable schedule.

1. Recurring → + Add.
2. Choose a type: income, expense, or credit card payment.
3. Set the amount (fixed, or variable with an estimated amount), frequency (weekly, biweekly, monthly, annual), start date, and optional end date.
4. Assign it to an account and, optionally, a category.
5. Enable or disable it at any time — disabled items are ignored by the forecast but kept for later.

Frequencies: weekly, biweekly, monthly, bimonthly, quarterly, semiannual, or annual. Weekly/biweekly items are scheduled by day of week; every other frequency is scheduled by day of month.

Once a recurring item's expected date passes, you can link an actual transaction to it from the account's transaction list so the forecast reflects reality going forward without double-counting that occurrence.

Every enabled recurring item is applied automatically on its scheduled date in the 90-day forecast. This is a free-tier feature — manual accounts, transactions, and recurring items are available on every plan.

7. Cash Flow Projections & Insights

How the 90-day forecast works

Starting from your real checking balances, Polaris walks forward day by day for 90 days, applying every enabled recurring item scheduled for that day and every credit card payment due that day as a projected checking outflow. The Dashboard chart is purely forward-looking — past transactions are not replayed into it. If a day's projected checking balance would go below zero, Polaris flags it with a warning so you can act before it happens.

What-If scenarios (Pro, Elite)

Pro and Elite users can run hypothetical scenarios (e.g. "what if I add a $400/month car payment?") against the forecast without altering your real baseline data.

Scenarios are named and saved, not thrown away after one look — you can keep several and revisit or delete them later.

Insights tab

A month-by-month breakdown of income, expenses, and investments, built from both actual transaction history and forecasted recurring events, with a net cash flow figure per month.

A transaction or recurring item is treated as an investment when its category or description contains a keyword like "invest", "savings", "retirement", "brokerage", "401k", or "ira" — so a transfer to a brokerage account shows up as investing, not as a regular expense dragging down your spending total.

Best Card Today (smart credit card recommendation)

When you have more than one eligible credit card, Polaris can estimate which card to put a purchase on based on each card's statement closing day, due day, and current utilization — surfacing the card that gives you the longest float before payment is due, or the one with the smallest projected impact on your average balance/utilization. Cards already near their credit limit are flagged or excluded from the recommendation.

The simulation defaults to a $100 purchase over a 60-day horizon (adjustable). A card already above 85% utilization gets a warning; above 95% it's excluded from the recommendation entirely rather than suggested despite being nearly maxed out.

8. Household Sharing

Polaris supports multi-user households from the ground up — useful for couples or families managing shared accounts.

1. Settings → Share Household → invite someone by email, picking their role.
2. The invited person opens Settings → Invitations to accept or decline.
3. Once accepted, they see the shared accounts and can act according to their role.

Roles:

Role	Can do
Owner	Full control: add/remove members, delete accounts, everything an editor can do
Editor	Add and edit accounts, transactions, and recurring items
Viewer	Read-only access to shared data

Household sharing itself is free on every plan — you can invite as many members as you like.

An invitation expires after 7 days if not accepted or declined. Changes any household member makes sync to everyone else in real time.

9. Notifications & Alerts

Daily & Weekly Updates (on by default)

Controlled by a single switch at Settings → Daily & Weekly Updates:

• Daily: a push notification and email on any day you have income, bills, or a credit-card payment due — summarized as a category count (e.g. "3 events — 1 income, 2 payments") rather than full details, as a reason to open the app. Skipped entirely on days with nothing scheduled.
• Weekly: an email digest of the coming week's events, sent once a week.

Turn the master switch off to stop both.

Account disconnect alerts (always on)

If a connected bank account's Plaid link breaks, you get a push notification and email immediately — this is independent of the Daily & Weekly toggle, since it's a functional problem with your data rather than a marketing nudge. Only the household member who originally connected the account is notified, since they're the one who can reconnect it.

Email on/off

A separate global email toggle in your account settings can turn off all outbound email entirely, including the above.

"Open Polaris" links in emails open the app directly on both Android and iOS instead of falling back to the marketing website.

10. Free vs. Paid Plans

Polaris has four tiers: Free, Basic, Pro, and Elite.

Feature	Free	Basic	Pro	Elite
Manual accounts, transactions, recurring items	Yes	Yes	Yes	Yes
90-day cash flow projection	Yes	Yes	Yes	Yes
Household sharing (invite members)	Yes	Yes	Yes	Yes
Insights (monthly income/expense/investment breakdown)	Yes	Yes	Yes	Yes
Daily & weekly notifications	Yes	Yes	Yes	Yes
Banner ads shown in-app	Yes	No	No	No
PDF statement import	No	Yes	Yes	Yes
Bank connections (Plaid)	No	No	Up to 2 accounts	Unlimited
AI Assistant (bring your own API key)	No	No	Yes	Yes
AI Assistant with built-in credentials (no API key needed)	No	No	No	Yes (metered quota)
What-if scenario simulations	No	No	Yes	Yes
Agent API access (external AI agent read access)	Yes	Yes	Yes	Yes
CSV export (accounts, recurring items, projections)	No	Yes	Yes	Yes
"Explain This Transaction" AI merchant lookup	No	No	Yes	Yes

Agent API access, where available, is currently read-only regardless of plan — an agent can read your accounts, projections, and financial context, but cannot yet create or edit transactions on your behalf.

11. Pricing & Subscription

Paid plans are each offered as Monthly, Yearly, and (where available) Lifetime purchase options, managed through RevenueCat on top of Apple's and Google's billing systems. Open Settings → Subscription (or any locked feature's upgrade prompt) to see the paywall with live, localized pricing for your store and region — prices aren't fixed figures quoted here since they can change and vary by platform/region/promotion.

Managing your subscription

• Subscribe: Settings → Subscription → pick Monthly or Yearly → complete the purchase through the App Store or Play Store.
• Restore purchases: on the paywall, if you've already paid (e.g. reinstalled the app, switched devices).
• Cancel: subscriptions are managed through your Apple ID or Google Play account settings, not inside Polaris directly — standard App Store/Play Store subscription management applies.
• What happens when you cancel: you keep your data; you simply lose access to paid features (bank connections, statement import, AI assistant, what-if scenarios) and drop back to Free until you resubscribe.

Subscription purchases are subject to Apple's/Google's standard auto-renewal terms; see Settings → Terms of Service for the full Terms of Use covering subscriptions.

12. Settings Reference

Preferences

• Default Currency — USD, EUR, GBP, or BRL.
• Theme — light, dark, or auto (follows system).
• Biometric Login — lock the app behind Face ID/Touch ID (or device equivalent).
• Prevent Screenshots — blocks screenshots/screen recording of the app for privacy.
• Daily & Weekly Updates — the engagement-notification master switch (see Notifications & Alerts).
• If Biometric Login is off, Polaris auto-locks after 15 minutes of inactivity and asks for your password to resume — enabling biometrics replaces that password prompt with Face ID/Touch ID.

Household & access

• Categories — manage your transaction categories.
• Share Household — invite members and manage roles.
• Invitations — accept or decline invites sent to you.
• Agent Access — create/revoke personal API keys so an external AI agent (e.g. Claude) can read your accounts, projections, and financial context over a REST API. Available on every plan, currently read-only. Each key can be scoped to specific accounts, and revoking one doesn't affect your others.

Subscription

• Subscription — shows your active plan and opens the paywall to upgrade, change cycle, or restore purchases.
• CSV export (Basic, Pro, Elite) — from the "…" header menu on a given tab: export account balances, recurring items, or the dashboard's 90-day projection as a CSV file, ready to share or open in a spreadsheet.

AI Assistant

• Enable Assistant — turns on the Assistant tab (Pro/Elite).
• Built-in Credentials (Elite) — use Polaris's own AI credentials instead of your own API key, against a metered quota (shown as "X/Y left").
• Provider — choose OpenAI or Gemini (when not using built-in credentials).
• API Key — add/remove your own provider API key.
• Model — pick which model to use; "Refresh" re-fetches the available model list from your provider.

When the assistant is in use, your questions and a summarized snapshot of your financial data are sent to whichever provider you've selected (your own, or Polaris's built-in one on Elite) — avoid putting highly sensitive information directly in a prompt.

Elite's built-in credentials currently run on Google's Gemini 2.5 Flash Lite, against a visible, metered quota ("X/Y left") rather than unlimited use. The same Pro/Elite assistant access also unlocks Explain This Transaction on any transaction's detail screen (see Transactions).

About

• About Polaris, User Guide, Privacy Policy, Terms of Service, and the current app Version.
• Report a Bug — see Bug Reporting & Feedback below.

Account

• Edit Profile — change your display name.
• Schedule Deletion / Cancel Deletion — see Account Management.
• Sign Out.

13. Bug Reporting & Feedback

Settings → Report a Bug lets you describe what went wrong and attach up to 3 screenshots or screen recordings. Submitting it files an issue directly against Polaris's internal issue tracker, attachments included — there's no separate email thread to manage. This is available on every plan.

14. Agent API — Connecting an External AI Agent

Available on every plan, Settings → Agent Access lets you create a personal API key so an external AI agent (Claude, ChatGPT, a script, an n8n workflow) can read your cashflow data directly.

Creating and managing keys

1. Settings → Agent Access → Create API Key.
2. Name it (e.g. "Claude Desktop"), choose a scope (Read only or Read & Write — see note below), and pick which accounts it can see (or all of them).
3. The raw key (pk_live_...) is shown exactly once — copy it immediately; Polaris never displays it again.
4. Revoke any key at any time without affecting your others; up to 10 active keys per account.

Read & Write currently behaves like read-only — no write endpoints exist yet, so an agent cannot create or edit transactions/recurring items through this API regardless of a key's scope.

Using it

Hand your AI agent the key plus the full integration guide at polariscashflow.com/agent-guide.md — it's written to be read directly by an agent and covers every endpoint with request/response examples.

• Base URL: https://us-central1-polaris-cdf95.cloudfunctions.net/agentApi/v1
• Auth: Authorization: Bearer pk_live_... on every request except /health.

Endpoint	Returns
GET /health	API status check, no auth needed
GET /me	Confirms the key works and what it's scoped to
GET /accounts	Every account the key can see: balance, type, institution
GET /projections?days=&accountId=	The 90-day cash flow projection (or fewer days), with daily events
GET /context	Everything at once: accounts, recent transactions, recurring items, projection, and a summarized snapshot — the same shape the in-app assistant uses

• Rate limits: 30 requests/minute burst, 2,000 reads/day per key, returned in X-RateLimit-* headers; going over either gets a 429 with Retry-After.
• Not yet available: writes of any kind, a standalone per-account transaction history endpoint beyond the 50 most recent in /context, and a standalone recurring-items list endpoint.

15. FAQ & Troubleshooting

Does Polaris read my bank credentials? No — your bank login is entered directly in Plaid's own connection flow, never typed into a Polaris form.

What happens to my data if I cancel a subscription? You lose paid-feature access, but your account data stays intact unless you separately delete your account.

Can I share with more than one person? Yes, via Settings → Share Household — invite as many members as you want, each with Editor or Viewer access.

How do I change my password? Use "Forgot Password" on the login screen to get a reset email.

I can't connect another bank account. Bank connections require Pro or Elite — on Pro you may have already used both of your 2 connection slots (upgrade to Elite for unlimited).

My Plaid account stopped syncing. Open Accounts or the account's detail screen and use the reconnect banner; if it still fails, disconnect and reconnect from scratch. You'll also get a push/email the moment the connection actually breaks.

My projection looks wrong. Check each recurring item's amount, frequency, start date, account, and enabled status; for variable items, confirm the estimated amount; for credit cards, confirm the closing day/due day and that a payment item exists.

Dashboard chart is empty. Add at least one checking account and at least one recurring item, then pull to refresh.

Assistant says an API key is required. Settings → AI Assistant → API Key, add/update it (or, on Elite, switch on Built-in Credentials instead).

Statement import fails. Confirm the PDF is text-based (not a scanned image) and under 10MB; try a different export from your bank's portal.

I can't delete an account. Only the account owner can — editors and viewers in a shared household cannot delete someone else's account.

What happens when a household invitation expires? It simply can no longer be accepted after 7 days — send a new one.

How long until a deleted account is actually gone? Scheduling deletion starts a 30-day grace period; you can cancel it any time before then from Settings → Account → Cancel Deletion. After 30 days it's permanent.

Why does my subscription say "Polaris Cash Flow Pro" instead of just "Pro"? Some early subscribers are still on a legacy entitlement name from before the Basic/Pro/Elite tiers existed — it still grants Pro-level access; nothing to do on your end.

Can I export my data? Yes — Basic, Pro, and Elite can export account balances, recurring items, or the dashboard's projection as CSV from the "…" menu in the header of the relevant tab.

What recurring frequencies are supported? Weekly, biweekly, monthly, bimonthly, quarterly, semiannual, and annual.

Does the AI assistant or Explain This Transaction see my bank login? No. They see a summarized snapshot of your accounts/transactions/projections, never your bank credentials, which only ever go through Plaid's own flow.

16. Getting the Most Out of Polaris

Once the basics are set up, a few habits make the forecast noticeably more accurate and useful:

• Keep recurring items current. The projection is only as good as what's in Recurring — update amounts when a bill changes, disable items that stopped, and set realistic estimates on variable ones.
• Link actual transactions to their recurring item once they post, so the forecast doesn't double-count an expected payment that already happened.
• Keep Daily & Weekly Updates on. It's the cheapest way to notice a due date or low-balance day before it arrives, without having to remember to open the app.
• Check Insights monthly, not just the Dashboard, to see actual income/expense/investment trends rather than just the forward-looking chart.
• Before a bigger purchase, run a What-If scenario (Pro/Elite) instead of guessing whether it fits — and check Best Card Today if you're deciding which credit card to put it on.
• Set household roles deliberately: Editor for whoever actively manages transactions/recurring items, Viewer for someone who just wants visibility.
• Export a CSV periodically (Basic+) as a point-in-time backup or to analyze in a spreadsheet, especially before making large changes to your accounts.

17. Support & Contact

• In-app: Settings → About Polaris, Privacy Policy, Terms of Service, or Report a Bug for the fastest path on an actual defect.
• Support email: support@polariscashflow.com
• Privacy/data requests: privacy@polariscashflow.com
• Website: polariscashflow.com
• Account deletion: request it from Settings → Account → Delete Account; it's scheduled with a grace period during which you can cancel it from the same screen before it's final.