# HSA Shoebox — User Guide

For people and AI agents adding expenses to this app. Read the first two sections and you can start; use the rest as reference.

The app keeps receipts and records for medical expenses paid **out of pocket**, so the HSA can reimburse them years later. Its job is to make each record hold up in an IRS audit decades from now.

---

## The short version

1. **Add** — photograph or upload the receipt. That is the whole job at the counter.
2. **Wait under a minute** — the app reads the receipt. The Add page shows when it is done.
3. **Review** — open it from **Home**. The receipt is shown next to what was read from it.
4. **Looks right** — pick who it was for, check the date and amount against the receipt, and press **Looks right**. The expense is filed and counts toward the balance.

Nothing is filed until a person presses **Looks right**.

---

## Where things are

| Place | Use it to |
|---|---|
| **Home** | See the amount ready to claim and everything waiting for review. |
| **Add** | Add a receipt (camera or file). Also: log a drive to medical care, import Amazon orders. |
| **Expenses** | Find any record. Search by merchant or description; filter by status, person, or year. |
| **Trends** (top bar on a computer; in the menu on a phone) | See what you paid over time, by type, place or person, and how the amount ready to claim has grown. Click a bar or a row to see the expenses behind it. Only filed expenses are counted. At the bottom, **Your HSA**: the balance, split into what was contributed and what it has grown by. |
| **Menu** (the round button, top right) | Imports, Withdrawals, Audit packet, Family & settings, Help, Sign out. |
| **?** (bottom right, on a computer) | See the steps for the page you are on, and a list of how-tos. It stays open while you work. |

Statuses: **To review** (waiting for a person), **Ready to claim** (filed), **Reimbursed** (matched to a withdrawal), **Not claiming** (kept on file, left out of the total).

---

## Ways to add an expense

| Expense | Where | Notes |
|---|---|---|
| Receipt, bill, statement | **Add** → *Take a photo* or *Choose files* | Photos and PDFs. Several files at once is fine; each becomes its own expense. |
| Driving to medical care | **Add** → *A drive to medical care* | Round-trip miles, plus parking and tolls. The IRS rate for the trip's year is applied. |
| Amazon purchases | **Add** → *Amazon orders* | Once a year. Follow the guide, upload the export, then accept or reject each line. Accepted lines are filed. |

---

## What an expense needs

Four things, and the app reads three of them for you:

| Needed | Notes |
|---|---|
| **The receipt or statement** | Attached when you add it. Mileage and Amazon order lines need none. |
| **Date of service** | When care was received or the item was bought. Must be on or after the HSA was established. |
| **Who it was for** | You, your spouse, or a dependent. One tap. |
| **What you paid** | Your share only, after any insurance. |

Merchant, description, date paid, payment method and type are kept when the app reads them. None of them is required. To correct anything, press **Edit details**; changes save as you make them. The rarely needed fields are under *More details*.

If the reader was unsure of a value it is marked **check**. Compare it with the receipt.

---

## When something needs a decision

| You see | Meaning | What to do |
|---|---|---|
| **This cannot be claimed as it stands** | The date of service is before the HSA was established. There is no override. | Correct the date if it is wrong. Otherwise press **Don't claim this**. |
| **This can be personal or medical** | Supplements, massage, gym, weight loss, special foods, exercise equipment, home modifications. | Attach a doctor's note (a letter, a prescription, or a visit note naming the condition), **or** write why it is medical. Either one clears it. |
| **This may not qualify** | The item looks like something the HSA does not cover. | If it does qualify, write why in your own words and press *Save reason*. Otherwise **Don't claim this**. |
| **Possible duplicate** | Another record has the same merchant, date and amount. | Open the other record. If they are separate expenses, tick *These are separate expenses*. If not, **Don't claim this** → *a duplicate*. |
| **Insurance paid part of this** | You pressed *Insurance paid part*. | Set the amount to what you owed and attach the insurance statement (an EOB, or a provider statement showing the insurance adjustment). |

---

## Edge cases

| Situation | Do this |
|---|---|
| **Insurance paid part of it** | Press *Insurance paid part*. Attach the EOB or provider statement. Claim only what you owed. |
| **The EOB has not arrived** | Add the receipt now and leave it in review. File it once the statement is attached. |
| **Receipt shows the full bill, not what you owed** | Press *Edit details* and set the amount to what you owed. |
| **Faded or unreadable receipt** | Upload it anyway. If it cannot be read, the expense is still created; enter the date, amount and person by hand. |
| **Only a bill, no proof you paid** | Add the payment confirmation or card statement line as a second document. |
| **One receipt, some items do not qualify** | Edit the amount to the qualifying items plus their share of tax. Say what was left out in *Notes*. |
| **One receipt covers two people** | Upload it once per person and give each their share. |
| **Two real charges, same place, day and amount** | File both. The second one asks you to confirm they are separate. |
| **Expense from before the HSA was established** | Not claimable. **Don't claim this** → *not a qualified medical expense*. |
| **Over-the-counter medicine, menstrual products** | Qualify with no prescription. Nothing extra is needed. |
| **Insurance premiums** | Generally not claimable. Exceptions: COBRA, coverage while on unemployment, Medicare at 65 or older (not Medigap), long-term-care insurance. |
| **Care for a spouse or dependent** | Fine, even if they are not on your health plan. The owner adds them under *Family & settings*. |
| **Old expense found years later** | Fine, as long as the date of service is on or after the HSA was established. |
| **Paid with the HSA debit card** | Add and file it, then match it under **Withdrawals** so the withdrawal is accounted for. |
| **Refund received after filing** | **Don't claim this** → *a mistake*, then add it again with the corrected amount. |
| **No mileage rate for that year** | The mileage form asks the owner for it on the spot. |

---

## Fixing mistakes

Records are never deleted. Every change is in the record's *History*.

| Status | Can it be edited? | How to fix |
|---|---|---|
| **To review** | Yes | *Edit details*. Changes save by themselves. |
| **Ready to claim** | No | **Don't claim this**, then add it again if needed. |
| **Not claiming** (not qualified) | — | *Claim this after all* puts it back in review. |
| **Not claiming** (duplicate or mistake) | No | It stays on file. Add the correct one again. |
| **Reimbursed** | No | Unmatch it under **Withdrawals** first. |

---

## Once a year

Under **Family & settings → Two questions a year**, the owner answers for each tax year:

1. Could an FSA, HRA, or another plan have paid any of the family's medical expenses?
2. Did you itemize medical expenses on Schedule A?

These answers go on the audit packet. If either is yes, each expense from that year asks for a confirmation before it can be filed.

## Every three months

The HSA's balance is copied in by hand, because the custodian's site has no way to send it. Home lists **Update the HSA balance** once it is more than three months old.

1. On the custodian's site (Fidelity NetBenefits), open the HSA. The **Summary** tab has the balance and its date. The **Contributing** tab has the contributions, one total for each year.
2. In the app, open **Trends** and, under **Your HSA**, press **Update**.
3. Enter the date, the balance, the contributions for every year added together, and anything ever taken out (0.00 if nothing). Press **Save**.

Each update adds a point to the line under **Your HSA**. Entered one under the wrong date? Open **Readings**, press **Remove** beside it, then **Remove it**.

---

## For AI agents

You are working in a real household's tax records. Accuracy matters more than speed.

**Getting in**
- A person signs you in. Never ask for, type, or store passwords or MFA codes.
- If you land on a sign-in page, stop and ask the person to sign in.

**You may, without asking**
- Upload receipts on **Add** and log trips under *A drive to medical care*.
- Correct fields under *Edit details* and attach documents.

**Only when the account owner has told you to, for that item**
- Press **Looks right**. That files the expense under the owner's name.
- Tick *These are separate expenses*, save a reason, or press **Don't claim this**.
- Accept or reject Amazon lines. Accepting files them.
- Change anything in **Family & settings**, match **Withdrawals**, or build an **Audit packet**.
- Update the HSA balance under **Trends**. Copy the figures exactly as the custodian's site shows them; never move money there.

**Rules**
1. **Check for duplicates first.** Search **Expenses** for the same merchant, date and amount before uploading.
2. **Never invent a value.** If a value is not on the document and you were not told it, leave it empty and say so in *Notes*.
3. **Never write a reason or a doctor's note yourself.** Those must come from the person or their doctor.
4. **Sign your work.** Start *Notes* with `Entered by AI agent on YYYY-MM-DD.` The *History* shows the signed-in person, not you.
5. **After uploading, wait for the Add page to show the expense as saved and read** before opening it.
6. **Amounts** are plain numbers (`42.17`). **Dates** use the date picker; check the displayed date matches the document.
7. **Finish with a report** to the person: each record you touched (its page address), its status, and what it still needs from them.

---

## When the app itself misbehaves

| Symptom | Try |
|---|---|
| A red *That did not work* box | Retry once. If it repeats, send the owner the message and the **request id** shown in the box. |
| A receipt is still "reading" after a few minutes | Check **Home**. If it is there with nothing filled in, enter the details by hand; the file is saved. |
| Upload fails | Check the connection and retry. Rows marked *Saved* are safe. |
| Sent back to sign-in | Your session expired. Sign in again; everything saved is safe. |