list-similar-products

Method: GET
Path: /catalog/products/similar

Tags: Catalog

Summary

Retrieve similar products

Description

Retrieves a list of products similar to a specified product based on their attributes and category. The similar products are returned sorted by relevance, with the most closely matching products appearing first. Useful for providing product recommendations to your customers.

Storefront SDK Usage

SDK Method: sdk.catalog.listSimilarProducts()

Example:

// Basic usage - get similar products for a specific product
const { data, error } = await sdk.catalog.listSimilarProducts({
  product_id: ["prod_01H9XYZ12345ABCDE"]
});

// Advanced usage with pagination and custom sorting
const { data, error } = await sdk.catalog.listSimilarProducts({
  product_id: ["prod_01H9XYZ12345ABCDE"],
  page: 1,
  limit: 20,
    sort_by: '{"relevance":"desc"}'
});

// Override customer group ID for this specific request
const { data, error } = await sdk.catalog.listSimilarProducts(
  {
    product_id: ["prod_01H9XYZ12345ABCDE"],
    page: 1,
    limit: 20
  },
  {
    "x-customer-group-id": "01H9XYZ12345USERID" // Override default SDK config
  }
);

if (error) {
  console.error("Failed to get similar products:", error.message);
} else {
  console.log("Similar products found:", data.products.length);
  console.log("Pagination:", data.pagination);

  data.products.forEach(product => {
    console.log(`Similar: ${product.name} - ${product.price}`);
  });
}

TypeScript Definition

"list-similar-products": {
        parameters: {
            query?: {
                /** @description no of rows per page */
                limit?: number;
                /** @description page number in pagination */
                page?: number;
                /** @description to retrieve similar products of specified products */
                product_id?: string[];
                /** @description json to sort records */
                sort_by?: string;
            };
            header?: {
                /** @description This param is used to determine product pricing, promotions, and subscription rates.  If a valid customer group id is provided, pricing details will be retrieved accordingly.  If no matching data is found for the specified customer group id, the system will fall back to the default customer group id.  If no data is found for the default group either, the highest applicable price will be returned. */
                "x-customer-group-id"?: components["parameters"]["CustomerGroupId"];
            };
            path?: never;
            cookie?: never;
        };
        requestBody?: never;
        responses: {
            /** @description Success response */
            200: {
                headers: {
                    [name: string]: unknown;
                };
                content: {
                    "application/json": {
                        message: string;
                        success: boolean;
                        content: {
                            products: components["schemas"]["Item"][];
                            pagination: components["schemas"]["Pagination"];
                        };
                    };
                };
            };
            401: components["responses"]["Unauthorized"];
            404: components["responses"]["NotFound"];
        };
    };

Component References

Reference	Resolves To
components["parameters"]["CustomerGroupId"]	CustomerGroupId
components["schemas"]["Item"]	Item
components["schemas"]["Pagination"]	Pagination
components["responses"]["Unauthorized"]	Unauthorized
components["responses"]["NotFound"]	NotFound

Parameters

• x-customer-group-id (header): This param is used to determine product pricing, promotions, and subscription rates. If a valid customer group id is provided, pricing details will be retrieved accordingly. If no matching data is found for the specified customer group id, the system will fall back to the default customer group id. If no data is found for the default group either, the highest applicable price will be returned.
• limit (query): no of rows per page
• page (query): page number in pagination
• product_id (query): to retrieve similar products of specified products
• sort_by (query): json to sort records

Responses

200

Success response

401

Not authorized for given operation on the Resource

404

Requested resource not found

OpenAPI Definition

{
  "tags": [
    "Catalog"
  ],
  "operationId": "list-similar-products",
  "summary": "Retrieve similar products",
  "description": "Retrieves a list of products similar to a specified product based on their attributes and category. The similar products are returned sorted by relevance, with the most closely matching products appearing first. Useful for providing product recommendations to your customers.",
  "externalDocs": {
    "url": "https://llm-docs.commercengine.io/storefront/operations/list-similar-products",
    "description": "API reference for the list-similar-products operation"
  },
  "parameters": [
    {
      "$ref": "#/components/parameters/CustomerGroupId"
    },
    {
      "name": "limit",
      "in": "query",
      "description": "no of rows per page",
      "schema": {
        "type": "integer"
      }
    },
    {
      "name": "page",
      "in": "query",
      "description": "page number in pagination",
      "schema": {
        "type": "integer"
      }
    },
    {
      "name": "product_id",
      "in": "query",
      "description": "to retrieve similar products of specified products",
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    {
      "name": "sort_by",
      "in": "query",
      "description": "json to sort records",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "message",
              "success",
              "content"
            ],
            "properties": {
              "message": {
                "type": "string"
              },
              "success": {
                "type": "boolean"
              },
              "content": {
                "properties": {
                  "products": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/Item"
                    }
                  },
                  "pagination": {
                    "$ref": "#/components/schemas/Pagination"
                  }
                },
                "required": [
                  "products",
                  "pagination"
                ],
                "type": "object"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    }
  },
  "security": [
    {
      "Authorization": []
    }
  ],
  "x-speakeasy-group": "catalog",
  "x-speakeasy-ignore": false,
  "x-speakeasy-name-override": "listSimilarProducts"
}

---

Auto-generated from OpenAPI spec and TypeScript definitions