# Understand the Shopping List API

In this module, you'll embark on a journey to understand and implement Shopping Lists, a powerful feature essential for enhancing the customer experience beyond immediate purchases.

Many e-commerce scenarios require persistent, shareable Product collections. Shopping Lists in commercetools address this need. They are more than just a "save for later" feature; they are a dynamic tool enabling features like:

- **Wishlists**: Users create lists of desired items.

- **Saved-for-later items**: Customers save Products they are interested in but not ready to purchase.

- **Gift registries**: Specialized wishlists for events like weddings or baby showers.

- **Collaborative purchase planning**: Multiple users contribute to a list.

- **Repeat order templates**: Storing frequently ordered items for quick re-ordering.

- **Public collections**: Retailers curate Product lists for marketing.

This module explores the technical implementation of Shopping Lists, covering their structure, core operations (CRUD), efficient querying, and advanced use cases like data enrichment and sharing patterns. We'll use a practical case study to illustrate real-world applications.

## Zen Electron Use Case

Zen Electron, a multi-brand electronics and appliances retailer, wants to implement a gift registry feature.

**Requirements**:

- Customers or guests can create private, named lists for special occasions.

- Guest-created lists should convert to customer-owned lists upon user registration or login.

- Lists should be store-specific, reflecting Zen Electron's Store model.

- Users should be able to make lists public through Custom Fields.

- Users should be able to share lists privately, not just publicly.

Throughout this module, we'll apply concepts to this case study, demonstrating how to implement the gift registry.

## How Shopping Lists Work (High-Level)

Shopping Lists are versatile entities within commercetools that allow users to create and manage collections of Products and custom text entries.

- **Association**: A Shopping List is linked to either a `customerId` (for registered users) or an `anonymousId` (for guest users). This linkage is crucial for retrieving user-specific lists and enables converting guest lists to customer-owned lists.

- **Content**: Lists hold items as `lineItems` (referencing specific Product Variants) or `textLineItems` (for custom text entries).

- **API Endpoints**: Shopping Lists are managed via dedicated API endpoints, such as `/shopping-lists` (general access) and `/in-store/key={storeKey}/shopping-lists` (store-specific access).

- **Limits & Cleanup**: Each project supports up to 10,000,000 Shopping Lists. The `deleteDaysAfterLastModification` field configures automatic deletion of inactive lists (default: 100 days), helping to maintain optimal database performance.

### Data structure

Understanding the Shopping List resource structure is key to implementation. In practice, you work with a small set of core types: `ShoppingList` and `ShoppingListDraft` for the resource itself, `ShoppingListLineItem` for catalog-backed entries, and `TextLineItem` for free-form entries. For the full JSON representation and related types, see the [ShoppingList API documentation](/api/projects/shoppingLists.md#shoppinglist).

The fields that usually matter first during implementation are the following:

| Field | Why it matters |
| --- | --- |
| `id` and `version` | Identify the Shopping List and support optimistic concurrency control for updates. |
| `name` and `slug` | Provide the user-facing title and a shareable, URL-friendly identifier. |
| `customer` or `anonymousId` | Associate the list with a registered Customer or a guest session. |
| `lineItems` and `textLineItems` | Store catalog-backed entries and free-form notes in the same resource. |
| `store`, `businessUnit`, and `deleteDaysAfterLastModification` | Scope the list to a business context and define cleanup behavior. |

### Line Items and Text Line Items

Shopping Lists contain two types of items:

- **`lineItems` (`ShoppingListLineItem`)**:

  - Represent specific Product Variants.

  - Unlike Cart Line Items (which snapshot full Product data), these contain references (`productId`, `variantId`) and key Product details (`name`, `productSlug`, `productType`, `published` status).

  - Include `quantity`, `addedAt`, and optional `custom` fields.

  - **Example**: Elena creates a list for her home theater:

    - `lineItem 1:` LG 65-inch OLED TV (product/variant ref, qty 1)

    - `lineItem 2:` Sonos Arc Soundbar (product/variant ref, qty 1)

    - `lineItem 3:` Premium HDMI Cable 2m (product/variant ref, qty 2)

- **`textLineItems` (`TextLineItem`)**:

  - Similar to `CustomLineItems` in Carts, these allow adding free-form items or notes (for example, products/services not in your catalog).

  - Include `name`, `description` (both localizable), `quantity`, `addedAt`, and optional `custom` fields.

  - **Example**: Frank adds notes for his home theater installation:

    - `textLineItem 1:` Name: `Installation notes`, Desc: `Mount soundbar above TV...` (qty 1)

    - `textLineItem 2:` Name: `Cable routing`, Desc: `Hide cables behind wall...` (qty 1)

    - `textLineItem 3:` Name: `Schedule install`, Desc: `Next Tuesday after 2 PM.` (qty 1)

For the complete specification, including the full JSON representation and every related type, see the [ShoppingList API documentation](/api/projects/shoppingLists.md#shoppinglist).

## Related pages

- [Area overview page with navigation](/learning-implement-carts-and-shopping-lists.md)
- [Previous page: Overview](/learning-implement-carts-and-shopping-lists/implement-shopping-lists/overview.md)
- [Next page: Find and manage existing Shopping Lists](/learning-implement-carts-and-shopping-lists/implement-shopping-lists/find-and-manage-existing-shopping-lists.md)
- [Search documentation and API specs](/search.md)