search-products
Method: POST
Path: /catalog/products/search
Tags: Catalog
Summary
Search products
Description
Search for products matching a specific words or characters given.
Storefront SDK Usage
SDK Method: sdk.catalog.searchProducts()
Example:
typescript
// Basic search
const { data, error } = await sdk.catalog.searchProducts({
query: "smartphone",
page: 1,
limit: 20
});
if (error) {
console.error("Failed to search products:", error);
return;
}
console.log("Search results:", data.skus?.length || 0, "products found");
console.log("Facet distribution:", data.facet_distribution);
console.log("Facet stats:", data.facet_stats);
console.log("Pagination:", data.pagination);
data.skus?.forEach(sku => {
console.log(`Found: ${sku.product_name} - ${sku.pricing?.selling_price}`);
});
// With filter (string expression — Meilisearch syntax)
const { data: filtered, error: filteredError } = await sdk.catalog.searchProducts({
query: "laptop",
filter: "pricing.selling_price 500 TO 2000 AND product_type = physical",
sort: ["pricing.selling_price:asc"],
facets: ["product_type", "categories.name", "tags"],
page: 1,
limit: 10
});
// With filter (array of conditions — combined with AND)
const { data: arrayFiltered, error: arrayError } = await sdk.catalog.searchProducts({
query: "shoes",
filter: ["product_type = physical", "rating >= 4", "stock_available > 0"],
sort: ["rating:desc"],
facets: ["*"],
page: 1,
limit: 25
});
// With filter (nested arrays — inner arrays use OR, outer uses AND)
const { data: nestedFiltered, error: nestedError } = await sdk.catalog.searchProducts({
query: "headphones",
filter: [
"pricing.selling_price 50 TO 300",
["product_type = physical", "product_type = bundle"]
],
page: 1,
limit: 25
});
// Override customer group ID for this specific request
const { data: overrideData, error: overrideError } = await sdk.catalog.searchProducts(
{
query: "laptop",
filter: "categories.name = computers",
page: 1,
limit: 20
},
{
"x-customer-group-id": "01H9XYZ12345USERID" // Override default SDK config
}
);TypeScript Definition
typescript
"search-products": {
parameters: {
query?: never;
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: {
content: {
"application/json": components["schemas"]["SearchProduct"];
};
};
responses: {
/** @description Success response */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": {
message: string;
success: boolean;
content: {
skus: components["schemas"]["Item"][];
facet_distribution: {
[key: string]: {
[key: string]: number;
};
};
facet_stats: {
[key: string]: {
min: number;
max: number;
};
};
pagination: components["schemas"]["Pagination"];
};
};
};
};
401: components["responses"]["Unauthorized"];
};
};Component References
| Reference | Resolves To |
|---|---|
components["parameters"]["CustomerGroupId"] | CustomerGroupId |
components["schemas"]["SearchProduct"] | SearchProduct |
components["schemas"]["Item"] | Item |
components["schemas"]["Pagination"] | Pagination |
components["responses"]["Unauthorized"] | Unauthorized |
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.
Request Body
Content Types: application/json
Responses
200
Success response
401
Not authorized for given operation on the Resource
OpenAPI Definition
json
{
"tags": [
"Catalog"
],
"operationId": "search-products",
"summary": "Search products",
"description": "Search for products matching a specific words or characters given.",
"externalDocs": {
"url": "https://llm-docs.commercengine.io/storefront/operations/search-products",
"description": "API reference for the search-products operation"
},
"parameters": [
{
"$ref": "#/components/parameters/CustomerGroupId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchProduct"
},
"examples": {
"in-operator": {
"summary": "IN operator (string)",
"value": {
"query": "shoes",
"filter": "product_type IN [physical,bundle]"
}
},
"and-string": {
"summary": "AND via string",
"value": {
"query": "shoes",
"filter": "rating > 4 AND product_type = physical"
}
},
"or-string": {
"summary": "OR via string",
"value": {
"query": "shoes",
"filter": "product_type = physical OR product_type = bundle"
}
},
"and-array": {
"summary": "AND via array",
"value": {
"query": "shoes",
"filter": [
"rating > 4",
"product_type = physical"
]
}
},
"or-nested-array": {
"summary": "OR via nested array",
"value": {
"query": "shoes",
"filter": [
[
"product_type = physical",
"product_type = bundle"
]
]
}
},
"mixed-and-or": {
"summary": "AND + OR mixed",
"value": {
"query": "shoes",
"filter": [
"product_type = physical",
[
"product_type = bundle",
"rating > 4"
]
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success response",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"message",
"success",
"content"
],
"properties": {
"message": {
"type": "string"
},
"success": {
"type": "boolean"
},
"content": {
"properties": {
"skus": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Item"
}
},
"facet_distribution": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
},
"facet_stats": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"min": {
"type": "number"
},
"max": {
"type": "number"
}
},
"required": [
"min",
"max"
]
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
},
"required": [
"skus",
"facet_distribution",
"facet_stats",
"pagination"
],
"type": "object"
}
}
}
}
},
"links": {
"AddItemToCart": {
"operationId": "update-cart",
"requestBody": {
"product_id": "$response.body#/content/skus/0/product_id",
"variant_id": "$response.body#/content/skus/0/variant_id"
},
"description": "Add a search result to a cart."
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"security": [
{
"Authorization": []
},
{
"X-Api-Key": []
}
],
"x-speakeasy-group": "catalog",
"x-speakeasy-ignore": false,
"x-speakeasy-name-override": "searchProducts"
}Auto-generated from OpenAPI spec and TypeScript definitions