Skip to main content

Favorite lists

Create, manage and display favorite lists using Propeller's GraphQL API. Favorite lists let users save products and clusters for quick access and reordering.

A favorite list belongs to one of three owner types:

OwnerFieldBehavior
CompanycompanyIdShared list, visible to all contacts in the company
ContactcontactIdPersonal list for a specific B2B contact
CustomercustomerIdPersonal list for a B2C customer

Fetching favorite lists​

Use the favoriteLists query to retrieve lists for a specific owner. Filter by companyId, contactId or customerId to scope the results.

query GetFavoriteLists($companyId: Int, $page: Int, $offset: Int) {
  favoriteLists(
    input: {
      companyId: $companyId
      page: $page
      offset: $offset
    }
  ) {
    items {
      id
      name
      companyId
      contactId
      customerId
      isDefault
      slug
      createdAt
      updatedAt
      products {
        itemsFound
      }
      clusters {
        itemsFound
      }
    }
    itemsFound
    page
    pages
  }
}

Variables:

{
  "companyId": 456,
  "page": 1,
  "offset": 10
}

Expected response:

{
  "data": {
    "favoriteLists": {
      "items": [
        {
          "id": "689615cf72635ff51c3471eb",
          "name": "Standard office supplies",
          "companyId": 456,
          "contactId": null,
          "customerId": null,
          "isDefault": true,
          "slug": "standard-office-supplies",
          "createdAt": "2026-01-15T09:30:00.000Z",
          "updatedAt": "2026-02-20T14:22:00.000Z",
          "products": {
            "itemsFound": 8
          },
          "clusters": {
            "itemsFound": 2
          }
        },
        {
          "id": "69a17974f21ab41940993034",
          "name": "Warehouse equipment",
          "companyId": 456,
          "contactId": null,
          "customerId": null,
          "isDefault": false,
          "slug": "warehouse-equipment",
          "createdAt": "2026-02-10T11:00:00.000Z",
          "updatedAt": "2026-02-27T11:01:31.000Z",
          "products": {
            "itemsFound": 3
          },
          "clusters": {
            "itemsFound": 1
          }
        }
      ],
      "itemsFound": 2,
      "page": 1,
      "pages": 1
    }
  }
}

The search input also supports filtering by name, isDefault, productIds (find lists containing specific products), clusterIds, createdAt and lastModifiedAt (with date range filters).

Fetching a single list with items​

Use the favoriteList query to retrieve a single list by ID, including its products and clusters:

query GetFavoriteList($id: String!) {
  favoriteList(id: $id) {
    id
    name
    isDefault
    slug
    products {
      items {
        ... on Product {
          productId
          names {
            language
            value
          }
          sku
          media {
            images(search: { sort: ASC, offset: 1 }) {
              items {
                imageVariants(
                  input: {
                    transformations: [
                      {
                        name: "thumbnail"
                        transformation: {
                          width: 100
                          height: 100
                          fit: BOUNDS
                          bgColor: "transparent"
                          canvas: { width: 100, height: 100 }
                        }
                      }
                    ]
                  }
                ) {
                  name
                  url
                }
              }
            }
          }
        }
      }
      itemsFound
    }
    clusters {
      items {
        ... on Cluster {
          clusterId
          names {
            language
            value
          }
          sku
          defaultProduct {
            media {
              images(search: { sort: ASC, offset: 1 }) {
                items {
                  imageVariants(
                    input: {
                      transformations: [
                        {
                          name: "thumbnail"
                          transformation: {
                            width: 100
                            height: 100
                            fit: BOUNDS
                            bgColor: "transparent"
                            canvas: { width: 100, height: 100 }
                          }
                        }
                      ]
                    }
                  ) {
                    name
                    url
                  }
                }
              }
            }
          }
        }
      }
      itemsFound
    }
  }
}

Expected response:

{
  "data": {
    "favoriteList": {
      "id": "69a17974f21ab41940993034",
      "name": "Warehouse equipment",
      "isDefault": false,
      "slug": "warehouse-equipment",
      "products": {
        "items": [
          {
            "productId": 104708,
            "names": [
              {
                "language": "NL",
                "value": "Elektrische Palletwagen EP-116"
              }
            ],
            "sku": "EP-116",
            "media": {
              "images": {
                "items": [
                  {
                    "imageVariants": [
                      {
                        "name": "thumbnail",
                        "url": "https://media.helice.cloud/example/images/en/cb853191-palletwagen.jpg?bg-color=transparent&canvas=100,100&fit=bounds&height=100&width=100"
                      }
                    ]
                  }
                ]
              }
            }
          }
        ],
        "itemsFound": 3
      },
      "clusters": {
        "items": [
          {
            "clusterId": 37952,
            "names": [
              {
                "language": "NL",
                "value": "Magazijnstelling Pro 200"
              }
            ],
            "sku": "MAG-PRO-200",
            "defaultProduct": {
              "media": {
                "images": {
                  "items": [
                    {
                      "imageVariants": [
                        {
                          "name": "thumbnail",
                          "url": "https://media.helice.cloud/example/images/nl/3ecf9984-stelling.png?bg-color=transparent&canvas=100,100&fit=bounds&height=100&width=100"
                        }
                      ]
                    }
                  ]
                }
              }
            }
          }
        ],
        "itemsFound": 1
      }
    }
  }
}

Favorite lists contain both products and clusters as separate collections. Use inline fragments (... on Product and ... on Cluster) to access their fields. Both collections support their own pagination through the input argument.

For cluster images, access the media through defaultProduct.media since clusters do not have a media field directly.

Favorite lists show products from all catalogs by default. In multi-store setups with different catalog root IDs, filter the products in the favorite list query by passing the catalog root ID to exclude products outside the current store's catalog.

Creating a favorite list​

Use favoriteListCreate to create a new list. Set one of companyId, contactId or customerId to assign ownership.

For a company (shared list):

mutation {
  favoriteListCreate(
    input: {
      companyId: 456
      name: "Warehouse equipment"
      isDefault: false
    }
  ) {
    id
    name
  }
}

Expected response:

{
  "data": {
    "favoriteListCreate": {
      "id": "69a17974f21ab41940993034",
      "name": "Warehouse equipment"
    }
  }
}

For a contact (personal B2B list):

mutation {
  favoriteListCreate(
    input: {
      contactId: 312
      name: "Lisa's project list"
      isDefault: false
    }
  ) {
    id
    name
  }
}

For a customer (B2C list):

mutation {
  favoriteListCreate(
    input: {
      customerId: 789
      name: "Wishlist"
      isDefault: false
    }
  ) {
    id
    name
  }
}

The isDefault field defaults to false. Setting it to true marks this as the primary list for the owner.

You can optionally include productIds and clusterIds in the create input to pre-populate the list with items on creation.

Adding products and clusters​

Use favoriteListAddItems to add products, clusters or both to an existing list. Items are appended to the list.

Adding products:

mutation {
  favoriteListAddItems(
    id: "69a17974f21ab41940993034"
    input: {
      productIds: [104708, 104923]
    }
  ) {
    id
    products {
      itemsFound
    }
    clusters {
      itemsFound
    }
  }
}

Expected response:

{
  "data": {
    "favoriteListAddItems": {
      "id": "69a17974f21ab41940993034",
      "products": {
        "itemsFound": 2
      },
      "clusters": {
        "itemsFound": 0
      }
    }
  }
}

Adding clusters:

mutation {
  favoriteListAddItems(
    id: "69a17974f21ab41940993034"
    input: {
      clusterIds: [37952]
    }
  ) {
    id
    products {
      itemsFound
    }
    clusters {
      itemsFound
    }
  }
}
{
  "data": {
    "favoriteListAddItems": {
      "id": "69a17974f21ab41940993034",
      "products": {
        "itemsFound": 0
      },
      "clusters": {
        "itemsFound": 1
      }
    }
  }
}

You can add products and clusters in the same call by providing both productIds and clusterIds.

The mutation returns the updated favorite list, so you can query the full product and cluster details in the response to refresh your UI immediately.

Removing items from a list​

Use favoriteListRemoveItems to remove specific products or clusters from a list:

mutation {
  favoriteListRemoveItems(
    id: "69a17974f21ab41940993034"
    input: {
      productIds: [104923]
    }
  ) {
    id
    products {
      itemsFound
    }
  }
}

Expected response:

{
  "data": {
    "favoriteListRemoveItems": {
      "id": "69a17974f21ab41940993034",
      "products": {
        "itemsFound": 1
      }
    }
  }
}

The input accepts the same structure as favoriteListAddItems. You can remove products, clusters or both in one call.

Updating a favorite list​

Use favoriteListUpdate to change the name or default status of a list:

mutation {
  favoriteListUpdate(
    id: "69a17974f21ab41940993034"
    input: {
      name: "Main warehouse supplies"
      isDefault: true
    }
  ) {
    id
    name
    slug
    isDefault
  }
}

Expected response:

{
  "data": {
    "favoriteListUpdate": {
      "id": "69a17974f21ab41940993034",
      "name": "Main warehouse supplies",
      "slug": "main-warehouse-supplies",
      "isDefault": true
    }
  }
}

The slug is automatically generated from the name.

The update input also accepts productIds and clusterIds. When provided, these replace the entire product or cluster list. This is different from favoriteListAddItems which appends items. Only send these fields if you intend to replace the full list contents.

Clearing all items​

Use favoriteListClearItems to remove all products and clusters from a list without deleting the list itself:

mutation {
  favoriteListClearItems(id: "69a17974f21ab41940993034") {
    id
    name
    products {
      itemsFound
    }
    clusters {
      itemsFound
    }
  }
}

Expected response:

{
  "data": {
    "favoriteListClearItems": {
      "id": "69a17974f21ab41940993034",
      "name": "Main warehouse supplies",
      "products": {
        "itemsFound": 0
      },
      "clusters": {
        "itemsFound": 0
      }
    }
  }
}

Deleting a favorite list​

Use favoriteListDelete to permanently remove a list and all its items:

mutation {
  favoriteListDelete(id: "69a17974f21ab41940993034")
}
{
  "data": {
    "favoriteListDelete": true
  }
}

Next steps​