Learning PathModule

Understand the Shopping List API

Learn how Shopping Lists function, their data structure, and the different types of items they can contain.

Ask about this Page
Copy for LLM
View as Markdown

After completing this page, you should be able to:

  • Explain the purpose of Composable Commerce Shopping Lists and identify common use cases, such as wishlists and gift registries.

  • Describe how Shopping Lists are associated with users by either a customerId or an anonymousId.
  • Distinguish between lineItems (representing Product Variants) and textLineItems (representing custom text entries) within the Shopping List data structure.

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 Composable Commerce 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 Composable Commerce 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.

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

FieldWhy it matters
id and versionIdentify the Shopping List and support optimistic concurrency control for updates.
name and slugProvide the user-facing title and a shareable, URL-friendly identifier.
customer or anonymousIdAssociate the list with a registered Customer or a guest session.
lineItems and textLineItemsStore catalog-backed entries and free-form notes in the same resource.
store, businessUnit, and deleteDaysAfterLastModificationScope 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.

Test your knowledge