> ## Documentation Index > Fetch the complete documentation index at: https://docs.spurtcommerce.com/llms.txt > Use this file to discover all available pages before exploring further. # Shopping List > Developer guide for installing, configuring, and integrating the Shopping List add-on. The **Shopping List (Shopping Cart) add-on** extends Picco360 / SpurtCommerce with customer-managed shopping lists and vendor-assisted cart management. Customers can create lists and manage products/SKU variants. Vendors can view customer lists, add products on a buyer's behalf, duplicate lists, record order conversions, and review dashboard analytics. > **Naming:** The source module is named `ShoppingCart`. The user-facing feature is referred to as Shopping List / Shopping Cart. This guide retains the source names for code, database tables, and API routes. ## Features ### Storefront customers * Create, rename, view, and delete shopping-list groups. * Add, update, and remove product/SKU line items. * View list subtotal and item count. * Retrieve enriched item details, including product, SKU, pricing, discount/special pricing, and stock status. * Use a lightweight list endpoint for dropdowns and SKU-in-list indicators. ### Vendors * View customer shopping lists with filters. * Add products to a customer's list, subject to tenant, stock, and quantity validation. * Duplicate a list for a customer. * View list details and products. * Mark a list as ordered for conversion tracking. ### Vendor analytics * Repeated products and repeat customers. * New-list and order-conversion counts. * Total revenue from ordered lists. * Date-grouped list and new-customer charts. * Trending products based on ordered lists. ## Architecture The add-on uses a layered architecture integrated with the platform's routing, dependency injection, ORM, and event-hook infrastructure. ```text theme={null} HTTP request | Tenant / authentication middleware | Controller -> DTO validation -> Service -> Repository -> TypeORM -> Database ^ | Platform events <---- ShoppingCartHook ``` *** Layer Responsibility *** Controllers Store and vendor HTTP endpoints using `routing-controllers`. Request DTOs Validate payloads with `class-validator` and `class-transformer`. Services Business logic and coordination through `typedi`. Repositories TypeORM access and custom reporting queries. Models Entities mapped to `shopping_cart` and `shopping_cart_detail`. Migrations Schema changes, plugin registration, and permission seeding. ## Hook Connects order-placement and customer-deletion events through `HookUtil`. ## Technology stack Area Technology *** Language / runtime TypeScript / Node.js Routing `routing-controllers` Dependency injection `typedi` ORM TypeORM Validation `class-validator`, `class-transformer` Database MySQL / MariaDB Dates `moment.js` Metadata `reflect-metadata` Platform integration `HookUtil`, `getDataSource` The supplied README does not state exact dependency version constraints. Confirm compatibility against the target SpurtCommerce/Picco360 application's package configuration. ## Directory structure ```text theme={null} ShoppingCart/ ├── ShoppingCartHook.ts ├── controllers/ │ ├── store/ │ │ ├── StoreShoppingCartController.ts │ │ ├── StoreShoppingCartDetailController.ts │ │ └── requests/ │ └── vendor/ │ ├── VendorShoppingCartController.ts │ ├── VendorShoppingCartDashboardController.ts │ └── requests/ ├── models/ │ ├── ShoppingCart.ts │ └── ShoppingCartDetail.ts ├── repositories/ │ ├── ShoppingCartRepository.ts │ └── ShoppingCartDetailRepository.ts ├── services/ │ ├── ShoppingCartService.ts │ └── ShoppingCartDetailService.ts └── migrations/ ├── 1747200087804-ShoppingCartPluginSeed.ts ├── 1747200372449-CreateShoppingCartTable.ts ├── 1747200938997-CreateShoppingCartDetailTable.ts ├── 1748514150206-AlterShoppingCartPluginSeed.ts ├── 1749279888714-AddCollumnIsOrdered.ts ├── 1750051962853-UpdatePluginRoutingUrl.ts ├── 1750066197446-AddCollumnShoppingCart.ts ├── 1751352779017-UpdatePluginRouteUrl.ts └── 1752584905864-AddVendorPermissionShoppingCart.ts ``` ### Main components *** Component Responsibility *** `StoreShoppingCartController` Storefront list-group operations. `StoreShoppingCartDetailController` Storefront line-item operations. `VendorShoppingCartController` Vendor list management, duplication, and order status. `VendorShoppingCartDashboardController` Vendor analytics endpoints. `ShoppingCartService` Shopping-list group business logic and query-builder listing. `ShoppingCartDetailService` Line-item business logic. `ShoppingCartRepository` Custom reports: repeated products/customers, revenue, and charts. ## `ShoppingCartDetailRepository` Line-item repository wrapper. ## Data model The add-on has two primary entities with a one-to-many relationship: ```text theme={null} ShoppingCart (1) -------- (N) ShoppingCartDetail ``` ### `ShoppingCart` --- `shopping_cart` Represents a shopping-list group owned by a customer within a tenant. *** Field Description *** `id` Primary key. `customer_id` Owning customer. `name` Shopping-list name. `is_default` Default-list flag. `is_active` Active flag. `is_delete` Soft-delete flag. `tenant_id` Tenant/vendor scope. `created_by`, `modified_by` Creator and last modifier user IDs. `created_date`, `modified_date` Creation and modification timestamps. `is_ordered` Whether the list has been ordered (`0` / `1`). `customer_user_id` Customer user ID. `created_by_type` Creator type: `seller` or `buyer`. ## `notes` List notes. When a customer creates a new default list, an existing default list is first changed to non-default. ### `ShoppingCartDetail` --- `shopping_cart_detail` Stores line items inside a list. *** Field Description *** `id` Primary key. `product_id` Product ID. `shopping_cart_id` Parent list ID; foreign key to `shopping_cart.id`. `sku_id` Selected SKU ID. `variant_option_id` Variant option ID. `variant_option_name` Variant option name. `quantity` Quantity; default `1`. `price` Unit price; `decimal(10,2)`, default `0.00`. `notes` Item notes. `is_active`, `is_delete` Active and soft-delete flags. ## Audit fields `created_by`, `modified_by`, `created_date`, `modified_date`. The detail table's foreign key cascades when its parent cart record is deleted. ## Storefront workflow and API The storefront endpoints allow customers to manage their own shopping-list groups and line items. 1. **Create a list** --- `POST /api/store-shopping-cart`. Uses `create-shopping-list`; a new list is marked as created by a buyer. If it becomes the default list, the existing default is unset. 2. **Add or update items** --- `POST /api/store-shopping-cart-detail`. Validates product/SKU, minimum and maximum quantity, and stock. If the same product + SKU already exists, its quantity is incremented. 3. **List groups** --- `GET /api/store-shopping-cart`. Returns lists with subtotal and item count. 4. **Dropdown data** --- `GET /api/store-shopping-cart/list`. Returns lightweight list data and indicates whether a SKU is already in a list. 5. **List detail** --- `GET /api/store-shopping-cart/:id/detail`. Returns line items enriched with product, SKU, pricing/discount, and stock information. 6. **Update a group** --- `PUT /api/store-shopping-cart/:id`. 7. **Delete a group** --- `DELETE /api/store-shopping-cart/:id`. 8. **Remove line items** --- `POST /api/store-shopping-cart-detail/delete`. *** Method Endpoint Permission Description *** `POST` `/api/store-shopping-cart` `customer`, `create-shopping-list` Create a list group. `PUT` `/api/store-shopping-cart/:id` `customer`, `create-shopping-list` Update a list group. `GET` `/api/store-shopping-cart/list` `customer`, `view-shopping-list` Lightweight dropdown list. `GET` `/api/store-shopping-cart` `customer`, `view-shopping-list` Customer list groups. `GET` `/api/store-shopping-cart/:id/detail` `customer`, List line-item `view-shopping-list-line-item` details. `DELETE` `/api/store-shopping-cart/:id` `customer`, `delete-shopping-list` Delete a list group. `POST` `/api/store-shopping-cart-detail` `customer`, Add/update line `edit-shopping-list-line-item` items. ## `POST` `/api/store-shopping-cart-detail/delete` `customer`, Remove line `delete-shopping-list-line-item` items. ## Vendor workflow and API Vendor operations are scoped to the vendor's tenant. 1. **List customer lists** --- `GET /api/vendor-shopping-cart`. Aggregates subtotal and item count, joins customer name, and supports customer, name, ordered-status, keyword, and date filters. 2. **Add an item** --- `POST /api/vendor-shopping-cart`. Validates tenant ownership, stock, and quantity limits; inserts or increments the line item and sends a customer notification using email template ID `60`. 3. **Duplicate a list** --- `POST /api/vendor-shopping-cart/create-duplicate`. Creates a new default list from an item list, validates product/SKU tenant ownership, and emails the customer. 4. **View list detail** --- `GET /api/vendor-shopping-cart/:id/detail`. 5. **View products** --- `GET /api/vendor-shopping-cart/:id/product-list`. 6. **Remove line items** --- `POST /api/vendor-shopping-cart/delete`. 7. **Mark as ordered** --- `PUT /api/vendor-shopping-cart/:id`, setting `is_ordered = 1`. *** Method Endpoint Permission Description *** `GET` `/api/vendor-shopping-cart` `vendor`, List customer `list-shopping-list` shopping lists. `POST` `/api/vendor-shopping-cart` `vendor`, Add an item to a `edit-shopping-list` customer's list; send notification. `POST` `/api/vendor-shopping-cart/create-duplicate` `vendor`, Duplicate a list `duplicate-shopping-list` for a buyer; send notification. `GET` `/api/vendor-shopping-cart/:id/detail` `vendor`, Retrieve list `list-shopping-list` details. `GET` `/api/vendor-shopping-cart/:id/product-list` `vendor`, Retrieve list `list-shopping-list` products. `POST` `/api/vendor-shopping-cart/delete` Not specified in README Remove line items. ## `PUT` `/api/vendor-shopping-cart/:id` `vendor`, Update ordered `edit-shopping-list` status. ## Vendor dashboard API All dashboard endpoints are under `/api/vendor-dashboard-shopping-cart` and are described as vendor-role endpoints. *** Method Endpoint Description *** `GET` `/api/vendor-dashboard-shopping-cart/reports/repeated-products` Products appearing in more than one list. `GET` `/api/vendor-dashboard-shopping-cart/reports/repeated-customers` Customers with at least one ordered list and at least two lists overall. `GET` `/api/vendor-dashboard-shopping-cart/new` Count of new, not-ordered lists. `GET` `/api/vendor-dashboard-shopping-cart/orders/conversions` Count of ordered lists. `GET` `/api/vendor-dashboard-shopping-cart/revenue/total` Revenue from ordered lists. `GET` `/api/vendor-dashboard-shopping-cart/chart-data` List counts grouped by date (week/month/year). `GET` `/api/vendor-dashboard-shopping-cart/customers/new` New-customer chart data. ## `GET` `/api/vendor-dashboard-shopping-cart/products/trending` Trending products based on ordered lists. The README does not provide report query parameters or detailed response schemas. Check `VendorShoppingCartDashboardController` and `ShoppingCartRepository` for those definitions. ## Response format The supplied README describes the platform response envelope as: ```json theme={null} { "status": 1, "message": "Success message", "data": {} } ``` `status` is documented as `1` or `0`. The exact `message` and `data` structure varies by endpoint. The source README does not include exact request DTOs or endpoint-level JSON examples; consult the relevant controller and request DTO before implementing a client. ## Hooks and cross-module integration `ShoppingCartHook.ts` self-registers with the platform's central `HookUtil`. It exposes repository-safe operations such as save, find, find-one, update, and delete-shopping-cart. Repository access is guarded so the hook can be called before the TypeORM `DataSource` is initialized or before the `ShoppingCart` entity is registered. *** Event Handler Behavior *** `shopping_cart_order` `handleOrder` Marks the referenced list `isOrdered = 1` when an order is placed. `shopping_list_order` `handleOrder` Alias for the order event. `shopping_cart_customer_delete` `handleCustomerDelete` Soft-deletes lists belonging to a deleted customer user. ## `shopping_list_customer_delete` `handleCustomerDelete` Alias for the customer-deletion event. The README does not specify the exact event payload. Inspect the hook implementation and platform event callers before emitting these events from another module. ## Permissions Migration `1752584905864-AddVendorPermissionShoppingCart.ts` seeds the **Shopping List** permission group (`slug_name = shopping-list`, sort order `32`). ### Vendor permissions Slug Name Listed *** `list-shopping-list` List Shopping List Yes `edit-shopping-list` Edit Shopping List No `duplicate-shopping-list` Duplicate Shopping List No ### Storefront permissions The store controllers reference these customer permissions: * `create-shopping-list` * `view-shopping-list` * `view-shopping-list-line-item` * `delete-shopping-list` * `edit-shopping-list-line-item` * `delete-shopping-list-line-item` Assign the relevant permissions to the appropriate customer and vendor roles in the host application. ## Database migrations Run migrations in timestamp order using the platform's TypeORM migration runner. *** Order Migration Purpose *** 1 `1747200087804-ShoppingCartPluginSeed.ts` Registers the ShoppingCart plugin (Sales type; initial vendor route). 2 `1747200372449-CreateShoppingCartTable.ts` Creates `shopping_cart`. 3 `1747200938997-CreateShoppingCartDetailTable.ts` Creates `shopping_cart_detail` and its cascading foreign key. 4 `1748514150206-AlterShoppingCartPluginSeed.ts` Updates/upserts the plugin record. 5 `1749279888714-AddCollumnIsOrdered.ts` Adds `is_ordered`. 6 `1750051962853-UpdatePluginRoutingUrl.ts` Updates vendor and dashboard plugin routes. 7 `1750066197446-AddCollumnShoppingCart.ts` Adds `customer_user_id`, `created_by_type`, and `notes`. 8 `1751352779017-UpdatePluginRouteUrl.ts` Adds store routes and create-duplicate route metadata. ## 9 `1752584905864-AddVendorPermissionShoppingCart.ts` Seeds the Shopping List vendor permission group and permissions. > **Production caution:** The supplied README says every migration `down()` method is a no-op and describes the migrations as forward-only. Back up the database and review migration behavior before applying them. Do not assume that a normal migration rollback will reverse these changes. ## Installation and setup The supplied README documents source-directory installation, not an npm package installation. It does not specify a package name, `npm install` command, or programmatic initialization function. ### 1. Add the source directory Copy the complete `ShoppingCart/` directory into the add-ons location used by your Picco360 / SpurtCommerce project. Preserve its directory structure. ### 2. Register the entities Ensure the host application's TypeORM configuration registers: * `ShoppingCart` * `ShoppingCartDetail` The README does not provide a ready-made entity array or host configuration snippet. Use the entity classes in `models/` and follow the registration convention for your platform version. ### 3. Run the migrations Run all nine migrations in the order shown above. Confirm that both tables, plugin metadata, route metadata, and permissions are present. ### 4. Register the hook Ensure `ShoppingCartHook.ts` is loaded during application bootstrap so it can register with `HookUtil`. Confirm that order-placement and customer-deletion flows invoke the expected event names. ### 5. Enable controllers and permissions The README states that controllers are discovered automatically by the platform's `routing-controllers` setup and do not require manual route registration. Verify that the host application's controller discovery includes the add-on's store and vendor controller directories. Assign the vendor and storefront permissions to the appropriate roles. ### 6. Verify the integration Test in a development or staging environment before production: * Application starts with both entities registered. * All migrations complete successfully. * Customers can create, view, update, and delete lists. * Customers can add, update, and remove line items. * Product/SKU, stock, and min/max quantity validation works. * Vendors can view lists and add products within their tenant. * Duplicate-list creation works and sends the expected notification. * Marking a list as ordered updates `is_ordered`. * Order and customer-deletion hooks execute correctly. * Dashboard reports return expected data for test records. ## Operational considerations * **Tenant isolation:** Preserve vendor tenant checks for lists, products, and SKUs. * **Inventory validation:** Keep stock and min/max quantity checks when extending line-item operations. * **Email notifications:** Vendor add-item and duplicate-list flows use email template ID `60`. Verify that the template and mail service are configured. * **Soft deletion:** The entities use `is_delete`; customer deletion is handled through a soft-delete hook. * **Order conversion:** `is_ordered` records conversion, and the order hook updates it. * **Forward-only migrations:** Back up the database and plan manual recovery before applying migrations to production. ## Troubleshooting *** Issue Checks *** Store/vendor routes are missing Check controller discovery and confirm plugin route migrations have run. Database or table errors Confirm both entities are registered and migrations ran in timestamp order. Vendor cannot access a list Check tenant ownership and the relevant vendor permission. Customer receives an authorization Check the customer's storefront error shopping-list permissions. Customer does not receive a Verify mail configuration and email notification template ID `60`. List is not marked ordered Verify the order flow emits `shopping_cart_order` or `shopping_list_order` with the payload expected by the hook. ## Dashboard report is empty Check test data, `is_ordered`, and the report query filters. ## Source files for deeper implementation details For exact DTO fields, event payloads, and report query parameters not present in the README, inspect: * `controllers/store/StoreShoppingCartController.ts` * `controllers/store/StoreShoppingCartDetailController.ts` * `controllers/vendor/VendorShoppingCartController.ts` * `controllers/vendor/VendorShoppingCartDashboardController.ts` * `controllers/store/requests/` * `controllers/vendor/requests/` * `models/ShoppingCart.ts` * `models/ShoppingCartDetail.ts` * `ShoppingCartHook.ts` * `repositories/ShoppingCartRepository.ts` * `services/ShoppingCartService.ts` * `services/ShoppingCartDetailService.ts` ## License The supplied README does not specify the add-on's license. Check the source repository's license file before redistribution or modification. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.