Shopping lists (shopping_lists)
Per-customer named bundles of (product, variant?, quantity, note?) rows. Buyers save recurring orders, then convert all or a selected subset of items into a Cart or a draft Quote Request in a single click. Conversions skip archived products and report them rather than failing the whole batch.
Public surface
All endpoints require an authenticated customer session and are scoped to
the (customer, organization) pair on the session.
| Verb + Path | Purpose |
|---|---|
GET /api/v1/shopping-lists | List the buyer's lists with their items |
POST /api/v1/shopping-lists | Create a new list |
GET /api/v1/shopping-lists/:id | One list with its items |
PATCH /api/v1/shopping-lists/:id | Rename, set line quantities, or both, in one write |
DELETE /api/v1/shopping-lists/:id | Delete (cascades to items) |
POST /api/v1/shopping-lists/:id/items | Add an item |
PATCH /api/v1/shopping-lists/:id/items/:itemId | Update quantity / note |
DELETE /api/v1/shopping-lists/:id/items/:itemId | Remove |
DELETE /api/v1/shopping-lists/:id/items | Clear the list (remove every item) |
POST /api/v1/shopping-lists/:id/convert-to-cart | Add items to the active cart; archived rows are skipped + reported |
POST /api/v1/shopping-lists/:id/convert-to-rfq | Add items to the draft RFQ; returns the rfqId for deep-linking, or rfqId: null when nothing converted (every selected item skipped, or none selected) and no quote request was created or changed |
The two converters accept an optional itemIds: string[] body. Empty or
missing array means "convert every item on the list".
PATCH /api/v1/shopping-lists/:id takes { name?, items?: [{ id, quantity }] }
— at least one of the two, each line at most once. It writes all of it or
nothing: a line that is not on the list refuses the whole request with
404 NOT_FOUND, and the list is left as it was. A body with only name
renames, as before.
On the storefront a list's page has one Save changes for the list's name and every line quantity. The conversion buttons submit the same form: what the buyer typed is saved first and then converted, so a conversion uses the quantities on screen, not the ones saved before. Remove and Clear list stay immediate actions.
The default list has its own three routes: GET /api/v1/shopping-lists/default
(created on first read when missing), POST /api/v1/shopping-lists/default/items
and POST /api/v1/shopping-lists/:id/set-default.
Organization permissions
The module declares two organization permissions, which an Organization's
administrator grants per role (organizations). Both are member-default, so an
Organization's Member role holds them from the start and nothing changes for
existing members.
| Code | Label | Gates |
|---|---|---|
shopping_lists.create | Create and edit shopping lists | POST /api/v1/shopping-lists, PATCH / DELETE …/:id, POST …/:id/items, PATCH / DELETE …/:id/items/:itemId, DELETE …/:id/items, POST …/default/items, POST …/:id/set-default |
shopping_lists.convert | Convert shopping lists into quote requests and carts | POST …/:id/convert-to-cart (with carts.create), POST …/:id/convert-to-rfq (with quote_requests.create) |
- Reading stays open. Listing one's own lists, reading one, and reading the default list need no permission.
- A conversion needs two permissions:
shopping_lists.convertand the target's create permission, whichcartsandquote_requestsdeclare. They are two separate checks, judged in that order; a refusal names the first one missing. - A refusal is
403 ORGANIZATION_PERMISSION_REQUIREDwith the code and its translated label indetails, answered before the request body or the list is looked at. - Saving a cart line to a list (
POST /api/v1/cart/items/:itemId/save-to-shopping-list) is acartsroute; it needsshopping_lists.createtoo. - The default list is still provisioned for every new member of an Organization, whatever their role: it is the platform's, not a write of the member's.
- Switched off, the module takes both permissions off the role editor and off every member's effective permissions; the grants stay stored and apply again once it is switched back on.
On the storefront a member without shopping_lists.create still reads their
lists. The lists page and a list's page offer no create, rename, delete,
quantity or remove controls; Add to shopping list is not offered on the
product page or the product cards, nor Save to list on a cart line. The page says why in one line: "Your
role allows viewing shopping lists but not changing them." Converting a list
(all lines or the selected ones) into the cart is offered only with
shopping_lists.convert and carts.create, and into a quote request only with
shopping_lists.convert and quote_requests.create.
Conversion semantics
ShoppingListService partitions the requested items by their referencing
product's status:
activeproducts go into the cart as one batch through the cart'saddItems(judged together with the cart, so the minimum order quantities apply), and into the RFQ viaRfqService.createForCustomer, whose customer-write minimum check applies.archivedproducts (or rows whose product no longer exists) are reported inskipped[]with one of:product_archivedproduct_not_foundvariant_unavailablebelow_minimum(cart only) — the product's total in the cart after the conversion would stay below a minimum order quantity; the skip carries theminimumthe line missed.
A product the buyer may no longer see, or that the channel does not publish,
is skipped as product_not_found — exactly like a deleted product, with no
name or minimum. Every other line is still added; the conversion is not rolled
back.
Availability is judged in the request's language: Accept-Language is read
as a q-weighted list and matched against the sales channel's languages
(exactly, then by base language), else the channel's default. The same rule
applies when an item is saved to a list (POST …/:id/items).
The HTTP response is always 200 OK with { shoppingListId, added, skipped } (plus rfqId for a quote request) so the UI
can show a friendly message rather than treating the partial result as
an error.
Entities
ShoppingList — (organizationId, customerAccountId, name).
ShoppingListItem — cascade-deletes with its parent list. The FK to
products is intentionally a plain uuid column without a CASCADE so a
product archive doesn't drop historical rows; the conversion service
surfaces them in the skip report instead.
Extension points
- Sharing within an organization — the entity has no
isSharedcolumn today; adding org-wide sharing means a column flip plus a one-line tweak to#owned()inshopping-list-service.ts. - Per-list deadlines — extend
ShoppingListwithexpiresAtfor procurement workflows that auto-archive stale lists. - Convert-to-quote-only-mode — the converter already returns an RFQ id; the storefront can deep-link the buyer into the draft to add a requester note before submission.