Essential Needs

Part of the Anaya Care Handbook — the source of truth for how the product must behave. When the product needs to change, change this document first, then make the system match it.

What this covers

This page governs essential needs: the running list of consumable items a client's household requires — groceries, personal-care supplies, medications, and everyday household items — tracked from Needed to Purchased by the care providers who buy them. Beyond a simple shopping list, this is the household's inventory of consumables: it tracks what is on hand, warns when stock runs low, captures spending, watches for waste, and builds shopping lists and purchase history. Because the care provider in the home is the person who knows what the household is out of, this page also governs how that knowledge becomes money well spent: items are added by searching a retailer live so they carry a real photo and a real price, bundled into an essential-needs request to the agency, and funded by the client's responsible party through a fund request before anyone shops. It sits alongside the client's everyday-life support documented in Meals, Engagement Activities, and Home Inventory.

Essential Needs is distinct from Home Inventory: Essential Needs manages consumable supplies that get used up and re-bought, while Home Inventory documents valuables and equipment — items of personal or financial significance that stay in the home.

Key terms

• Essential need — a single consumable item the client's household requires — a grocery, a personal-care supply, a medication, or a household item — tracked from Needed to Purchased.
• Recurring item — an essential need that automatically reappears as a fresh Needed item at a chosen interval (weekly, every two weeks, or monthly).
• Inventory — the household's running count of consumable items on hand, used to know what is stocked and what needs re-buying.
• Low-stock alert — a notification raised when an item's on-hand count falls to or below a set threshold, so it can be added back to the list before it runs out.
• Meal-based grocery tracking — grocery items pulled automatically from the client's 30-day meal plan so the ingredients each meal needs flow into the essential-needs list without manual re-entry.
• Shopping list — an auto-generated, grouped list of currently Needed items the care provider can carry to the store.
• Waste-reduction monitoring — tracking items that expired or went unused so the household can adjust how much it buys.
• Standing library — a client's essential-needs list, which persists: an item bought last month is the same item the household runs out of this month, so it is re-requested rather than re-entered.
• Retailer lookup — a live search of a retail feed at the moment someone adds an item. Nothing is stored as a catalog; only a snapshot of the chosen product is kept on the client's item.
• Product snapshot — what the retailer said about a product when it was attached: name, brand, size, photo, shelf price, the store that quoted it, and when. Provenance, never rewritten.
• Reference store — the shop a client's prices are quoted from, resolved from that client's own address. The care provider shops near the client's home, so the prices should be from there.
• Restock — returning a purchased item to Needed, opening a new cycle. It never alters the purchase history.
• Purchase history — the permanent, append-only record of every purchase of an item: who bought it, when, how many, at what cost, and against which request.
• Essential-needs request — a bundle of currently Needed items a care provider submits to the agency for funding, carrying an itemized budget estimate.
• Fund request — an approved essential-needs request forwarded to the client's responsible party: the same itemized, priced list, which they explicitly approve or decline before any shopping happens.
• Budget estimate — the sum of quantity × estimated cost across a request's items, shown with the itemized list and labelled as an estimate everywhere it appears.
• Responsible party — defined under Clients. Here, the person who approves or declines fund requests.

How it works

Each client has a running list of needed items — groceries, personal-care supplies, medications, or everyday household items — each with a category, quantity, priority, and estimated cost. When a care provider buys an item they mark it purchased, recording who bought it, when, the actual cost, and photos of the receipt. The list shows running totals of estimated versus actual spend.

Adding an item from the retailer

Typing item names by hand makes every estimated cost a guess. So when someone adds an essential need they search a retail feed live, see the product's photo, size and shelf price, and pick it — and the item's name, photo and estimated cost fill themselves in. Nothing is kept as a catalog: only a product snapshot is stored on that client's item, recording what the retailer said and when. Anything the feed does not carry can still be typed by hand; it simply has no photo and a hand-entered estimate.

The classification is always ours. A retailer supplies a product; it does not know whether that product is a grocery or a medical supply in an eldercare sense, so whoever adds the item chooses the item type, category and unit.

Prices are quoted from a store near the client, resolved from the client's own address and remembered, because the care provider shops near the client's home rather than near the office. Two consequences are deliberate. The same product can be priced differently for two clients, which is correct rather than a bug. And where no store can be resolved — an address the retailer does not reach, or no address at all — the search still returns photos but no prices, says so plainly, and asks for an estimate instead of showing $0.

A shelf price is an estimate, never a quote, and the price taken is never a promotional one: a promotion expires, and a budget approved against one would understate the real shop a week later. The item keeps the estimated cost it was added with, so a later price change never rewrites a request a family has already approved.

The list is a standing library

A household's essential needs repeat. What it ran out of last month it runs out of again, so the list persists: an item stays on it after being bought and is restocked — returned to Needed — when it is needed again, rather than being searched for and re-entered. That is what makes the list worth curating.

Because the same item is bought many times, a purchase is no longer a single set of fields that the next purchase overwrites. Every purchase is appended to the item's own purchase history: who bought it, when, how many, at what cost, and against which request. A recorded purchase is permanent; restocking opens a new cycle and never edits one.

Requesting funds from the responsible party

The care provider in the home knows what the household is out of — but they should never have to spend their own money or chase the family for it. The money conversation is a two-step chain: the provider asks the agency, and the agency asks the family.

The provider — typically on the mobile app, on site — bundles currently Needed items into an essential-needs request. Because each item carries an estimated cost, the request carries an itemized budget estimate — pictures, quantities, prices, and a total — before it is ever sent. The agency reviews the bundle, adjusting quantities or removing items where needed, and approves or declines it. Approval turns it into a fund request to the client's responsible party: the same itemized, priced list, which they explicitly approve or decline. Once funded, the provider shops, marks each item purchased with its receipt and actual cost as usual, and the request closes showing estimated versus actual spend side by side.

Until Anaya Wallet ships, no money moves through the platform: payment happens however the family and agency already handle it — a transfer, a cash float, the agency's invoice — and the fund request is the record of the ask, the sign-off, and the reconciliation. The Wallet does not change this flow; it slots underneath it as the payment rail, so that approving a fund request charges the responsible party and settles the money to the agency before anyone shops, instead of the agency fronting the cost and the family reimbursing it afterwards (NEED-12). Individual after-the-fact purchases stay possible for small buys that never needed a fund request.

Inventory and low-stock alerts

Beyond the shopping list, the household keeps a count of consumables on hand. Each item can carry a low-stock threshold; when the on-hand count falls to or below that level, the platform raises a low-stock alert and the item is added back to the list as Needed so it can be re-bought before it runs out.

Meal-based grocery tracking

Groceries do not all have to be entered by hand. The client's 30-day meal plan (see Meals) lists the ingredients each meal needs, and those grocery items flow automatically into the essential-needs list. As the meal plan is approved or changed, the grocery side of the list follows it.

Shopping lists and purchase history

Currently Needed items are assembled into an auto-generated shopping list, grouped so a care provider can shop efficiently. Every purchase is kept in a permanent purchase history — what was bought, by whom, when, and at what cost — feeding the spend totals and the waste-reduction view.

Expense and waste-reduction monitoring

The list tracks estimated versus actual spend so the household can see where money goes. Waste-reduction monitoring watches for items that expired or went unused, so future quantities can be adjusted down and over-buying reduced.

Rules

1. NEED-1 — An essential-need item is always either a medical supply or a grocery, always has a category and a priority, and always starts as Needed.
2. NEED-2 — Only Needed items can be edited, deleted, or marked purchased. A recorded purchase is permanent and can never be edited or deleted; a Purchased item returns to Needed only through an explicit restock, which opens a new cycle and never alters a recorded purchase.
3. NEED-3 — Marking an item purchased must record who bought it, when, the actual cost if known, and any receipt photos.
4. NEED-4 — An item marked recurring (weekly, every two weeks, or monthly) must automatically reappear as a fresh Needed item at that interval.
5. NEED-5 — Essential-need lists are visible only to logged-in users whose role permits it, and never cross agency boundaries.
6. NEED-6 — The household must keep an on-hand count of consumable items, and each item may carry a low-stock threshold. (🚧 Spec only)
7. NEED-7 — When an item's on-hand count falls to or below its low-stock threshold, the platform must raise a low-stock alert and add the item back to the list as Needed. (🚧 Spec only)
8. NEED-8 — Grocery items from the client's approved 30-day meal plan must flow automatically into the essential-needs list, and must follow the meal plan as it is approved or changed. (🚧 Spec only)
9. NEED-9 — Currently Needed items must be assembled into an auto-generated, grouped shopping list a care provider can shop from. (🚧 Spec only)
10. NEED-10 — Every purchase must be kept in a permanent, append-only purchase history on the item, recording who bought it, when, how many, the actual cost, and the request it was made against. Buying the same item again adds an entry; it never overwrites one.
11. NEED-11 — The list must track waste — items that expired or went unused — so future quantities can be adjusted to reduce over-buying. (🚧 Spec only)
12. NEED-12 — In a future release, an approved fund request must be paid through Anaya Wallet: approval charges the responsible party for the request's total and settles those funds to the agency before any shopping begins, so neither the agency nor the care provider fronts the cost. (🚧 Spec only)
13. NEED-13 — Adding an essential need must offer a live retailer search, and an item added that way must store a product snapshot — the retailer, its product reference, the name, photo, size, price, the store that quoted it, and when it was taken. Nothing is stored as a shared catalog. The retailer supplies the product; the item type, category, and unit are always chosen by the person adding it, because no retailer knows this product's eldercare classification.
14. NEED-14 — Prices must be quoted from a store resolved from the client's own address, not from a single platform-wide or agency-wide setting, and that store must be recorded so a price can be traced to it. Where no store can be resolved, the search must return products without prices and say so, and must never present an unpriced item as costing nothing.
15. NEED-15 — Picking a searched product must pre-fill the essential need — name, photo, and estimated cost — and the search must always show the photo and the price. A value the person adding the item supplies always wins over the retailer's. Free-typed items remain allowed for anything the retailer does not carry.
16. NEED-16 — An item keeps the estimated cost it was added with, and its product snapshot is never rewritten: a later price change at the retailer must never alter an existing item or a request that contains it. The price a family is asked to approve must be read at the moment of adding, on the server, never taken from whatever the browser last saw.
17. NEED-17 — A reference price is an estimate, never a quote. Every budget estimate must be labelled as an estimate wherever it appears, and actual spend comes only from receipts. (🚧 Spec only — a request's total is labelled an estimate, but the item list still shows a bare figure)
18. NEED-18 — A care provider must be able to bundle currently Needed items into an essential-needs request whose itemized budget estimate — quantity × estimated cost per item, with a total — is shown before it is submitted. A client's representative may raise a request the same way, for their own household only: asking is not approving, and the request still passes agency review (NEED-19) before it returns to them as a fund request. Raising a request is a grantable permission, not an inherent one — an agency that wants requests to originate only with its own staff can revoke it from representatives.
19. NEED-19 — Only agency management (owner, admin, or staff allowed to manage essential needs) may approve, adjust, or decline a submitted essential-needs request. Declining requires a reason, and every adjustment made during review is recorded on the request. (🚧 Spec only — approve and decline-with-reason are built; adjusting a request during review is not)
20. NEED-20 — Approving a request must send a fund request — the itemized, priced list — to the client's responsible party, who must explicitly approve or decline it. When the responsible party gives their answer off-platform, agency management may record it on their behalf; such a decision must be clearly marked as recorded-on-behalf and name who recorded it. Recording an off-platform approval must also require an account of how the answer was obtained — who gave it and how they were reached — because marking a request funded commits money the family was never shown a screen to approve, and a name and a timestamp do not assert that anybody was asked. Recording an off-platform decline requires no such account: it commits nothing and returns the items to the list. No purchase is recorded against a request before it is funded.
21. NEED-21 — A funded request closes only when every one of its items is purchased (with receipt, per NEED-3) or removed, and must present estimated versus actual spend side by side.
22. NEED-22 — Every submission, approval, adjustment, decline, funding, and completion of a request must notify the other parties to it and be recorded in the platform activity log. (🚧 Spec only — every step is written to the activity log; none of them notifies anybody)
23. NEED-23 — Until Anaya Wallet ships, no money moves through the platform: the fund request records the ask, the approval, and the reconciliation, and payment happens outside it. When the Wallet ships, this flow is unchanged — the Wallet becomes the payment rail beneath it, per NEED-12.
24. NEED-24 — A purchased item must be restockable back to Needed, which resets only the current cycle — quantity, purchaser, cost, and receipts — and never the purchase history. An item still bundled into an in-flight request can never be restocked, or that request could never close.
25. NEED-25 — An essential need added from a retailer must keep a permanent reference to that retailer's product — which retailer, its product id, and when the snapshot was taken — so any price on the list can be traced back to what was quoted and by whom.

Note: This page's rules were retired from the old Daily Living page: DAILY-15 – DAILY-18 → NEED-1 – NEED-4. IDs are never reused.

Who can do what

Decisions needed

• Which essential-need purchases should require a funded Anaya Wallet request versus being recorded after the fact (NEED-12) — for example, a cost threshold or item type above which sign-off and funding are mandatory.
• How low-stock thresholds are set per item (NEED-6, NEED-7) — a default by category, a per-item value, or both — and whether a representative or only agency staff can change them.
• Retailer feed details (NEED-13) — one feed, not two: the Kroger Public Products API (official, free, 10,000 calls/day; prices require a store id, which is why the store is resolved from the client's address). The second commercial feed, planned for medical supplies, is no longer needed — a live check returned real photos and shelf prices for incontinence underwear, gauze pads, nitrile exam gloves, disposable bed pads and even cane tips, so one free feed covers both halves of the list. Amazon's PA-API was ruled out separately (deprecated May 2026; its successor requires sustained affiliate sales). Still open: whether the feed operator's terms permit storing its data and hotlinking product images, and whether a live search on every keystroke stays inside the daily call budget as the platform grows.
• Prices are store-local to the client. Which currency a household prices in, and what should happen for a client the feed reaches no store near at all, remain open.
• A reference store is not always the obvious brand. The feed's operator runs many store banners, and in several states none carry the parent brand's name — a California client resolves to Ralphs, Food 4 Less or Foods Co, all valid. Anywhere the store is shown or chosen must present the banner the feed actually returned rather than a single brand name, or someone will conclude there is no coverage near their client.
• Whether a client's resolved store should be changeable by hand — a household that shops somewhere other than the nearest store — is undecided. Today it is resolved automatically and re-resolved only if the client's address changes.
• Whether a cost threshold lets a small essential-needs request skip the responsible-party step and be funded by the agency directly (the same threshold question as NEED-12).
• Whether an unanswered fund request gets reminders and an expiry, mirroring the Wallet's WALLET-8.