# The shopping list

> One list the household shares, sorted by aisle, that works in a supermarket basement with no signal and tells everyone when somebody is already at the store.

The shopping list gets used in the worst signal of anything in the app: a
parent, a cart, a supermarket basement, one bar. It is built for that
moment.

Every workspace has one, on every plan. Open **Shopping** in the sidebar (on
the phone, from the contents list), **The list** on the family hub's Meals &
shopping card, or type "Shopping list" into the command palette. The first
time, **\[Start your grocery list]** makes the list. In your own workspace you
share it with the one other person you invited.

## Adding things

Type the item and press enter. As you type, the aisle it belongs in appears as a
chip you can tap to change. Put the amount in with the name if that is quicker:
`milk x2`, `2x bread`, `3 avocados` or `2 kg flour` fill the quantity for you,
shown as a chip you can remove. `2% milk` stays milk.

A whole list can come in at once from capture. Type or say "milk eggs bread
butter" or "a dozen eggs, 2 cans tomatoes and peanut butter" into capture and
it shows as separate items before you save, and one tap on the add button
under them puts each one on the list as its own line, amount included. See
[A list stays a list](https://themarginapp.com/docs/notes#a-list-stays-a-list).

If this workspace's list can't take them (it is full on Free) and another of
your workspaces can, capture and voice offer that one by name, "Add 4 to
Groceries in Rivera Family", and the items go there. The line that confirms
it, on the web and the phone, has an Open link that switches to that
workspace and shows the list.

Items are grouped into 13 aisles, and the aisles run in the order you walk a
store: Produce, Bakery, Meat & Seafood, Dairy & Eggs, Pantry, Snacks, Drinks,
Frozen, Household, Personal Care, Baby, Pets, and Other last. Reading the list
top to bottom is the route.

The aisle guess comes from a plain list of keywords, with no network call, so
it works in airplane mode. Longer phrases win over single words, which is why
"ice cream" lands in Frozen and not in Dairy. An item it does not recognize
gets no aisle and sits under Other, because a wrong guess saved to the list is
harder to spot than a blank one.

Margin Intelligence can add to the list too, and so can any assistant you
have [connected](https://themarginapp.com/docs/agents-and-mcp). Its items look like anyone else's, with
one small mark beside them. Hover over it, or tap it on a phone, to see who
asked and through which connection: "Added by Alex through" and the name you
gave that connection. It reads offline like the rest of the list.

Adding by voice from Siri, Google Assistant or Alexa ("add milk to the
shopping list") is built and still being set up, so it is not on your phone or
speaker yet. On Pro, Family and Team, Zapier, Make and n8n can add items
today. See
[Voice](https://themarginapp.com/docs/voice#siri-google-assistant-and-alexa) and
[Integrations](https://themarginapp.com/docs/integrations#zapier-make-and-n8n).

## When something new arrives

A row that turns up while the list is open grows into its place in line, and the
rows below it move down to make room. That covers an item your partner adds from
another phone, the ingredients a planned dinner drops in, and anything an
assistant adds. Several at once step in a moment apart, so six ingredients read
as six rows joining rather than the page jumping.

Opening the list never animates, and neither does the first sync on a new
device: those rows were already yours. With reduced motion turned on, new rows
appear in place with no movement.

Each aisle heading carries a small drawn mark (a leaf for Produce, a loaf for
Bakery, a snowflake for Frozen) in your theme's ink.

## At the store

1. Tap **I'm at the store**. Everyone else sees your name and that you are
   there, which saves the second trip and the duplicate milk.
2. Tap each thing as it goes in the cart. The whole row is the target, sized
   for a thumb, and the list records who checked it off and when.
3. Checked items collect under **In the cart**, with a count.
4. Tap **Finish run**. Type what you spent if you want it logged to
   Expenses and press **Log & finish**, or leave the amount blank and finish.
   Either way the run ends and the checked items clear.

## Prices and a running total

Tap an item and give it a price, what you expect that line to cost as
written ("2 packs" means both packs). Prices are in the workspace's own
currency. As soon as one item has a price, a line above the list shows the
running total and what is already in the cart, and says how many items have
no price yet, so the figure never pretends they were free.

When the checked items carry prices, **Finish run** offers
their sum as the amount. The receipt is still the truth, so change it if the
register said otherwise. In a household, Finish also asks **Who paid?**, even
before there is an amount. Pick the person whose card it was. Once an amount
is in, **Split it?** appears: split equally with everyone or leave it **Not
split**. A split is the same one the Expenses page
makes, and it shows up under Balances. Changed your mind about going? Use
**Not going** instead; it ends your trip without logging a run.

> **On the phone:** On the phone the price is in the item's edit sheet, and the running total
> sits under the store banner with a **Record as expense**
> button for what is in the cart.

**Clear checked** empties the cart at any time without ending a
run.

Not going after all? Tap **Not going** on your own banner. The run is
released and nobody is shown at the store. If someone else is out and you are
taking over, tap **Take over**.

## Undoing a mistap

Claiming the run, taking it over, letting it go, checking off an item, removing one
and clearing the cart each show a short message with **Undo**. Undo
puts the list back exactly as it was. An undone claim leaves no name on the
banner and no "claimed a minute ago", and an undone check goes back to whoever
checked it before, at the same time. It works with no signal, like everything
else here.

Undo does nothing if someone has changed the same thing since. If a partner
took over the run after your mistap, Undo leaves their claim alone and says so.
Once the message is gone, the banner's **Not going** still releases your
claim.

> **On the phone:** In the phone app you check off an item by swiping its row. The banner and its
> **I'm at the store**, **Not going** and **Take over** buttons sit
> above the list, and the same Undo shows above the add bar. A long press on an
> item opens it to change the name, amount, aisle or whether it is a staple, and
> to remove it.

## Staples

Mark the things you buy every week with **Make a staple** on the row. A
staple you check during a shop goes in the cart like anything else. When the
shop ends, with **Clear checked** or **Finish run**, a staple is
never deleted. It parks with the usual things, and one tap puts it back on.

Staples are counted on their own. The household page, the dashboard and the
wall show how many things there are to buy, and the staples still on the list
as a separate number, so a list with conditioner and five staples reads
"1 thing to buy, plus 5 staples" rather than six.

## Items from the meal plan

**Add this week's meals** puts the ingredients of the week's
planned meals on the list. Each one names the meal it is for ("for Sheet-pan
lemon chicken"), so you can tell what the plan added from what people typed.
When two meals need the same thing it shows once, with the amounts added up,
and names both ("for Stir-fry and Curry"). Checking it off checks it for both. See [Recipes and the meal
plan](https://themarginapp.com/docs/recipes-and-meals).

Press it again and the amounts are topped up to what the week now needs. If
you doubled Thursday's dinner, the 8 chicken thighs the plan put there become
16, and the message says which amounts went up. Nothing is ever lowered, and a
press with nothing changed adds nothing.

A line you typed or edited yourself is never overwritten, and neither is one
you already checked off. What it holds still counts, and anything the plan needs
beyond it goes on as its own line, marked "Top-up for the meal plan". When the
two amounts are in different units ("2" and "500 g"), both lines stay so you
can decide in the store. Singular and plural count as one unit, so "1 can" on
the list and "3 cans" in the plan become one line of 3 cans.

The same rule runs when a planned meal adds itself to the list, and when you
press **Add to the shopping list** on a recipe page: amounts go up, nothing
you wrote is overwritten, and a second press with nothing changed adds nothing.

The household can also have planned meals add themselves to the list, from
**Family settings → Meals**.

## With no signal

Adding, checking off, editing, claiming the run and finishing it all work with no
connection. They write to the database on your phone and sync when signal
returns, so there is never a spinner to wait on.

![Use your shopping list with no signal (24 seconds, filmed in the Try it sandbox).](https://themarginapp.com/docs/media/ep03/list-no-signal.webp)

_Use your shopping list with no signal (24 seconds, filmed in the Try it sandbox)._

**Shopping with no bars**

1. Open the list before you lose signal, or any time after: it is already on
   your phone, so it opens in a basement aisle too.
2. Tap each thing as it goes in the cart. It moves to **In the cart**
   straight away, with nothing to wait for.
3. Keep going: add, edit and check off as usual.
4. When you are back online the changes sync on their own, and everyone at
   home sees what you bought.

![The Groceries list with Lemons checked off while the device had no connection](https://themarginapp.com/docs/media/ep03/list-ticked-offline.webp)

_Lemons checked off with the connection turned off. The line under the title is the list's own reminder that it works with no signal._

![The same list on a phone, with Lemons checked off offline](https://themarginapp.com/docs/media/ep03/list-ticked-offline-mobile.webp)

_The same list on a phone._

> **Known limit: The meals button needs signal** **Add this week's meals** reads the plan from the server.
> Offline it says "Couldn't reach the meal planner" and leaves the list alone,
> rather than showing you an empty week.

## Send the list to a delivery app

On a laptop, press **Delivery** beside the list's name. On the phone, open
**This list** and choose **Send to a delivery app**.

- **Copy the list** (or **Share** it) as plain text, grouped by aisle, with
  only what is still to get. Paste it into Instacart, Walmart, Kroger or any
  other app's search, or into a message.
- **Find each item at** Instacart, Walmart or Kroger turns every line into a
  link to that store's own search, one tap per item.

The Margin does not fill a delivery cart for you. Each of those stores only
lets an app add to your cart under a partner agreement, and we would rather say
so than pretend. Margin Intelligence and connected assistants can hand over the
same list with `export_shopping_list`.

To show the list to someone who is not on The Margin, press
**Link** beside the list's name for a view-only link. See
[Sharing and permissions](https://themarginapp.com/docs/sharing-and-permissions#a-view-only-link-for-someone-not-on-the-margin).

## Store reminders (phone app)

The phone app can remind you of the list when you walk into a store. Open
**This list**, choose **Remind me near a store**, switch it on, and add a store
where you are standing or by its address. When you next arrive, the phone shows
"You're near Trader Joe's: 6 things on Groceries: milk, eggs, bread and 3
more."

- It needs location set to **Always** (iPhone) or **Allow all the time**
  (Android), asked only when you switch it on, because the phone has to notice
  the store while the app is closed.
- Everything stays on the phone. Your stores and your location are never sent
  to The Margin, and the reminder is built from the list the phone already
  holds.
- One reminder per store every two hours, and none when the list is empty.

A browser cannot watch for a place in the background, so this lives only in
the phone app. On the web and the installed web app, the list is the same list.

## What it does not do yet

There is no list import yet. Coming from Cozi, paste the list into the chat
and ask Margin Intelligence to add it;
[The Margin as a Cozi alternative](https://themarginapp.com/alternatives/cozi) covers the rest of the
move.

> **Known limit: One list, in practice** The app makes one list per household and has no rename or delete. The
> assistant can make more, and when there are several the app shows them as
> tabs across the top.

> **Known limit: Notes on items** An item's note shows on its row, and the assistant can write one. The edit
> dialog covers the name, amount, price, aisle and staple, but not the note.

> **For agents:** `add_shopping_item`, `check_shopping_item`, `list_shopping_items`,
> `claim_shopping_run` and `finish_shopping_run` do what the buttons do.
> Items take a `price`, `list_shopping_items` returns the running total, and
> `finish_shopping_run` with `use_item_prices` logs the priced total.
> `add_meals_to_list` is the meal-plan button. A `name` that is a list
> ("milk, eggs and 2 loaves of bread", or one per line) is added as one line per
> item, and the answer lists them under `items`. Spaces alone never split it, so
> "chocolate milk" stays one item. With no `quantity`, an amount at the front of
> the name is read into it: "2 cans tomatoes" is tomatoes, 2 cans.

## Availability

The shopping list is on every plan. Free keeps one list with up to 30 items on
it at a time; ticked-off items don't count, so finishing a run makes room. Near
the limit the add field says how many items are on the list before you type,
and at 30 it says so instead of taking a letter it can't keep. Pro, Family and
Team have no limit and as many lists as you like. Pulling in the week's meals
needs the meal plan, which is Family. See [Plans and limits](https://themarginapp.com/docs/plans-and-limits).

**Where to next**

- [Recipes and the meal plan](https://themarginapp.com/docs/recipes-and-meals): where the week's ingredients come from
- [Working offline](https://themarginapp.com/docs/working-offline): what a basement with no signal can and cannot do
- [The wall display](https://themarginapp.com/docs/the-wall-display): the list on a screen in the hall


---

Section: Together. Checked against the running product on October 25, 2026.
Web page: https://themarginapp.com/docs/the-shopping-list. Every docs page: https://themarginapp.com/docs/llms.txt