Understand the Shopping List API

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

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 Commercetools 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. Shopping Lists are represented in JSON format.

Key components:
  • ShoppingList: The main resource.
  • ShoppingListDraft: Used for creating new lists.
  • ShoppingListPagedQueryResponse: Structure for paginated query results.
  • ShoppingListReference and ShoppingListResourceIdentifier: Ways to reference lists.
  • ShoppingListLineItem and ShoppingListLineItemDraft: Represent Product Variant line items and their drafts.
  • TextLineItem and TextLineItemDraft: Represent text-based line items and their drafts.
Shopping List JSON Representation Example:
 {
  "id": "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version": 1,
  "name": {
    "en": "My shopping list"
  },
  "key": "my-shopping-list",
  "description": {
    "en": "New description"
  },
  "customer": {
    "typeId": "customer",
    "id": "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug": {
    "en": "my-shopping-list"
  },
  "lineItems": [
    {
      "id": "ade85d60-736b-4ca8-87ed-01fde78f92c5",
      "productId": "077bb11b-0d00-4e00-aced-48f493a79da0",
      "name": {
        "en": "Product name"
      },
      "productType": {
        "typeId": "product-type",
        "id": "a941b0b1-5c8f-41de-99e4-de965714d89f"
      },
      "variantId": 2,
      "quantity": 1,
      "addedAt": "2022-08-22T14:11:03.572Z"
    }
  ],
  "textLineItems": [
    {
      "id": "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
      "name": {
        "en": "My shopping list item"
      },
      "description": {
        "en": "This is a good gift idea"
      },
      "quantity": 5,
      "addedAt": "2022-08-22T14:11:03.572Z"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "deleteDaysAfterLastModification": 100,
  "store": {
    "typeId": "store",
    "key": "b2c-retail-store"
  },
  "createdAt": "2022-08-22T14:11:03.587Z",
  "lastModifiedAt": "2022-08-22T14:11:03.587Z"
 }
Key Fields Explained:
  • id: The unique, immutable system identifier.
  • version: Essential for optimistic concurrency control. Each update requires the current version number.
  • key: An optional, user-defined unique identifier, useful for business logic or integration.
  • name: A localizable field for the list's user-facing name.
  • description: A localizable field for additional details.
  • customer: Reference to the associated Customer (if not anonymous).
  • anonymousId: Identifier used if the list belongs to a guest user (not shown in example).
  • slug: A localized, URL-friendly identifier, often used for sharing or direct linking.
  • lineItems: Array of ShoppingListLineItem objects (see below).
  • textLineItems: Array of TextLineItem objects (see below).
  • store: Optional reference for multi-store contexts.
  • businessUnit: Optional reference for B2B contexts.
  • deleteDaysAfterLastModification: Configures automatic cleanup (days).
  • custom: Allows extending the list with your own defined data structures (Types and Fields).
  • createdAt / lastModifiedAt: Timestamps for creation and last modification.

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, see the ShoppingList API Documentation.

Test your knowledge