# Search

Product search and discovery

## Search products with faceted filtering

> Performs a full-text search across products with support for faceted\
> filtering, sorting, and pagination. Returns matching products along\
> with available filter facets and sorting options.\
> \
> \*\*How Search Works:\*\*\
> \
> When a search request is received, the system first checks if the same\
> search with identical parameters has been performed recently. If found\
> in cache, results are returned immediately.\
> \
> If no cached result is found, the search process begins. The system\
> queries Elasticsearch, which stores product metadata (not full product\
> data). The fields used for querying include: \`in\_stock\`, \`price\`,\
> \`basket\_offer\_ids\`, \`category\_ids\`, and \`collection\_ids\`.\
> \
> \*\*Product Extraction Strategies:\*\*\
> \
> After receiving results from Elasticsearch, products are extracted using\
> one of the following strategies:\
> \- \*\*DefaultProductExtractionStrategy\*\*: Returns all product IDs that\
>   matched the search\
> \- \*\*FirstItemSearchExtractionStrategy\*\*: Returns the first sub-product\
>   from each meta product\
> \- \*\*ListableFirstProductExtractionStrategy\*\*: Returns listable products\
>   when meta products contain sub-products\
> \- \*\*MinPriceFirstProductExtractionStrategy\*\*: Returns sub-products sorted\
>   by minimum price in ascending order\
> \- \*\*MaxPriceFirstProductExtractionStrategy\*\*: Returns sub-products sorted\
>   by maximum price in ascending order\
> \- \*\*AllSubProductsExtractionStrategy\*\*: Returns all sub-product IDs\
>   belonging to meta products\
> \
> \*\*Product and Facet Conversion:\*\*\
> \
> After extraction, two conversion processes occur:\
> 1\. \*\*Product Conversion\*\*: Product IDs from Elasticsearch are fetched\
>    from the database in the order they were returned, maintaining search\
>    relevance ordering\
> 2\. \*\*Facet Conversion\*\*: Facet data (filterable attribute IDs) is used\
>    to fetch attribute values from the database and create filter widgets.\
>    Widget types are determined by \`FacetConfiguration\` database records:\
>    \- If a Facet Configuration exists for the attribute, it specifies the\
>      widget type, aggregation settings, and display options\
>    \- If no Facet Configuration exists, fallback rules apply:\
>      \- \`category\_ids\` uses Category Widget\
>      \- \`basket\_offer\_ids\` uses Promotion Widget\
>      \- All other attributes default to Multi Select Widget\
>    \- Widget configurations support translation for multi-language sites\
>    \- Widgets include choices with quantities, labels, selection states,\
>      and URLs for filtering\
> \
> \*\*Filtering Support:\*\*\
> \
> The search supports filtering by various attributes including:\
> \- Stock availability (in\_stock)\
> \- Price ranges (price)\
> \- Categories (category\_ids)\
> \- Collections (collection\_ids)\
> \- Sellers (seller\_ids)\
> \- Basket offers (basket\_offer\_ids)\
> \- Discount amounts and ratios (discount\_amount, discount\_ratio)\
> \- Category paths (category\_paths)\
> \- Custom product attributes (attributes\_\*)\
> \- Custom fields (custom\_\*)\
> \
> \*\*Pagination and Sorting:\*\*\
> \
> Results are paginated and can be sorted using available sort options.\
> The default page size is configurable via the \`SEARCH\_DEFAULT\_PAGE\_SIZE\`\
> dynamic setting and can be overridden via the \`page\_size\` parameter.\
> Maximum page size is limited to 250 items.\
> \
> Sort options are configured through the \`SortOption\` database model and\
> managed via the administration interface. Each sort option defines:\
> \- Display label (translatable)\
> \- Parameter value used in the \`sorter\` query parameter\
> \- Elasticsearch sort configuration (field paths, directions, nested queries)\
> \- Display order and visibility settings\
> \
> When a sort option is selected, its Elasticsearch configuration is applied\
> to the search query. Sort options automatically adapt to inventory strategy\
> context, adjusting price field references when multiple price lists are\
> active. A secondary sort by product listing ID ensures consistent ordering\
> across pages.\
> \
> \*\*Fuzzy Search:\*\*\
> \
> When fuzzy search is enabled (\`SEARCH\_FUZZY\_SEARCH\_ACTIVE\`) and the\
> query is longer than 4 characters, the search includes approximate\
> matches with typo tolerance (fuzziness level: 1).

```json
{"openapi":"3.1.0","info":{"title":"Search API - Product Discovery & Image Search","version":"1.0.0"},"tags":[{"name":"Search","description":"Product search and discovery"}],"servers":[{"description":"Default commerce site","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce storefront hostname"}}}],"paths":{"/list/":{"get":{"tags":["Search"],"operationId":"searchProducts","summary":"Search products with faceted filtering","description":"Performs a full-text search across products with support for faceted\nfiltering, sorting, and pagination. Returns matching products along\nwith available filter facets and sorting options.\n\n**How Search Works:**\n\nWhen a search request is received, the system first checks if the same\nsearch with identical parameters has been performed recently. If found\nin cache, results are returned immediately.\n\nIf no cached result is found, the search process begins. The system\nqueries Elasticsearch, which stores product metadata (not full product\ndata). The fields used for querying include: `in_stock`, `price`,\n`basket_offer_ids`, `category_ids`, and `collection_ids`.\n\n**Product Extraction Strategies:**\n\nAfter receiving results from Elasticsearch, products are extracted using\none of the following strategies:\n- **DefaultProductExtractionStrategy**: Returns all product IDs that\n  matched the search\n- **FirstItemSearchExtractionStrategy**: Returns the first sub-product\n  from each meta product\n- **ListableFirstProductExtractionStrategy**: Returns listable products\n  when meta products contain sub-products\n- **MinPriceFirstProductExtractionStrategy**: Returns sub-products sorted\n  by minimum price in ascending order\n- **MaxPriceFirstProductExtractionStrategy**: Returns sub-products sorted\n  by maximum price in ascending order\n- **AllSubProductsExtractionStrategy**: Returns all sub-product IDs\n  belonging to meta products\n\n**Product and Facet Conversion:**\n\nAfter extraction, two conversion processes occur:\n1. **Product Conversion**: Product IDs from Elasticsearch are fetched\n   from the database in the order they were returned, maintaining search\n   relevance ordering\n2. **Facet Conversion**: Facet data (filterable attribute IDs) is used\n   to fetch attribute values from the database and create filter widgets.\n   Widget types are determined by `FacetConfiguration` database records:\n   - If a Facet Configuration exists for the attribute, it specifies the\n     widget type, aggregation settings, and display options\n   - If no Facet Configuration exists, fallback rules apply:\n     - `category_ids` uses Category Widget\n     - `basket_offer_ids` uses Promotion Widget\n     - All other attributes default to Multi Select Widget\n   - Widget configurations support translation for multi-language sites\n   - Widgets include choices with quantities, labels, selection states,\n     and URLs for filtering\n\n**Filtering Support:**\n\nThe search supports filtering by various attributes including:\n- Stock availability (in_stock)\n- Price ranges (price)\n- Categories (category_ids)\n- Collections (collection_ids)\n- Sellers (seller_ids)\n- Basket offers (basket_offer_ids)\n- Discount amounts and ratios (discount_amount, discount_ratio)\n- Category paths (category_paths)\n- Custom product attributes (attributes_*)\n- Custom fields (custom_*)\n\n**Pagination and Sorting:**\n\nResults are paginated and can be sorted using available sort options.\nThe default page size is configurable via the `SEARCH_DEFAULT_PAGE_SIZE`\ndynamic setting and can be overridden via the `page_size` parameter.\nMaximum page size is limited to 250 items.\n\nSort options are configured through the `SortOption` database model and\nmanaged via the administration interface. Each sort option defines:\n- Display label (translatable)\n- Parameter value used in the `sorter` query parameter\n- Elasticsearch sort configuration (field paths, directions, nested queries)\n- Display order and visibility settings\n\nWhen a sort option is selected, its Elasticsearch configuration is applied\nto the search query. Sort options automatically adapt to inventory strategy\ncontext, adjusting price field references when multiple price lists are\nactive. A secondary sort by product listing ID ensures consistent ordering\nacross pages.\n\n**Fuzzy Search:**\n\nWhen fuzzy search is enabled (`SEARCH_FUZZY_SEARCH_ACTIVE`) and the\nquery is longer than 4 characters, the search includes approximate\nmatches with typo tolerance (fuzziness level: 1).","parameters":[{"$ref":"#/components/parameters/SearchTextParameter"},{"$ref":"#/components/parameters/PageParameter"},{"$ref":"#/components/parameters/PageSizeParameter"},{"$ref":"#/components/parameters/SorterParameter"},{"$ref":"#/components/parameters/DefaultPageSizeParameter"},{"$ref":"#/components/parameters/ElasticsearchValueParameter"},{"$ref":"#/components/parameters/ExtractionStrategyParameter"},{"$ref":"#/components/parameters/InventoryStrategyParameter"},{"$ref":"#/components/parameters/InStockParameter"},{"$ref":"#/components/parameters/PriceParameter"},{"$ref":"#/components/parameters/CategoryIdsParameter"},{"$ref":"#/components/parameters/CollectionIdsParameter"},{"$ref":"#/components/parameters/SellerIdsParameter"},{"$ref":"#/components/parameters/BasketOfferIdsParameter"},{"$ref":"#/components/parameters/DiscountAmountParameter"},{"$ref":"#/components/parameters/DiscountRatioParameter"},{"$ref":"#/components/parameters/CategoryPathsParameter"},{"$ref":"#/components/parameters/DataModeParameter"}],"responses":{"200":{"description":"Search results retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}}}}}},"components":{"parameters":{"SearchTextParameter":{"name":"search_text","in":"query","description":"Search query text","required":false,"schema":{"type":"string"}},"PageParameter":{"name":"page","in":"query","description":"Page number (1-indexed)","required":false,"schema":{"type":"integer","minimum":1}},"PageSizeParameter":{"name":"page_size","in":"query","description":"Number of results per page. Maximum value is 250. If not specified,\nthe default page size from SEARCH_DEFAULT_PAGE_SIZE dynamic setting\nis used.\n","required":false,"schema":{"type":"integer","minimum":1,"maximum":250}},"SorterParameter":{"name":"sorter","in":"query","description":"Sort option value","required":false,"schema":{"type":"string"}},"DefaultPageSizeParameter":{"name":"default_page_size","in":"query","description":"Default page size for pagination. This value is used when page_size\nparameter is not provided. The actual page size will be the minimum\nof this value and the maximum allowed page size (250). If not provided,\nuses the SEARCH_DEFAULT_PAGE_SIZE dynamic setting value\n","required":false,"schema":{"type":"integer","minimum":1,"maximum":250}},"ElasticsearchValueParameter":{"name":"elasticsearch_value","in":"query","description":"Custom Elasticsearch sort value to override or extend the default\nsorting behavior. When provided, this value is prepended to the\nselected sorter's Elasticsearch value. Can be a single value or\ncomma-separated list of values. Used for advanced sorting customization\nin Elasticsearch queries\n","required":false,"schema":{"type":"string"}},"ExtractionStrategyParameter":{"name":"extraction_strategy","in":"query","description":"Product extraction strategy class path. Determines how products are\nextracted from Elasticsearch results, especially when dealing with meta\nproducts and sub-products. If not provided, uses the value from\nSEARCH_PRODUCT_EXTRACTION_STRATEGY dynamic setting, or defaults to\nDefaultProductExtractionStrategy. Available strategies:\n- DefaultProductExtractionStrategy: Returns all matching product IDs\n- FirstItemSearchExtractionStrategy: Returns first sub-product from each meta product\n- ListableFirstProductExtractionStrategy: Returns listable products when meta products contain sub-products\n- MinPriceFirstProductExtractionStrategy: Returns sub-products sorted by minimum price (ascending)\n- MaxPriceFirstProductExtractionStrategy: Returns sub-products sorted by maximum price (ascending)\n- AllSubProductsExtractionStrategy: Returns all sub-product IDs belonging to meta products\n","required":false,"schema":{"type":"string"}},"InventoryStrategyParameter":{"name":"inventory_strategy","in":"query","description":"Inventory strategy identifier. Used in shops with multiple inventory\nsystems to determine which price list should be used. When provided,\nprice fields are prefixed with the price list ID (e.g., price_1234\ninstead of price). If not provided, uses the basket's inventory\nstrategy or defaults to the standard inventory\n","required":false,"schema":{"type":"integer"}},"InStockParameter":{"name":"in_stock","in":"query","description":"Filter by stock availability (comma-separated values)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},"PriceParameter":{"name":"price","in":"query","description":"Filter by price range (comma-separated values)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},"CategoryIdsParameter":{"name":"category_ids","in":"query","description":"Filter by category identifiers (comma-separated)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"integer"}}},"CollectionIdsParameter":{"name":"collection_ids","in":"query","description":"Filter by collection identifiers (comma-separated)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"integer"}}},"SellerIdsParameter":{"name":"seller_ids","in":"query","description":"Filter by seller/data source identifiers (comma-separated)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"integer"}}},"BasketOfferIdsParameter":{"name":"basket_offer_ids","in":"query","description":"Filter by basket offer/promotion identifiers (comma-separated)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"integer"}}},"DiscountAmountParameter":{"name":"discount_amount","in":"query","description":"Filter by discount amount range (comma-separated min, max)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},"DiscountRatioParameter":{"name":"discount_ratio","in":"query","description":"Filter by discount ratio range (comma-separated min, max)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},"CategoryPathsParameter":{"name":"category_paths","in":"query","description":"Filter by category paths (comma-separated)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},"DataModeParameter":{"name":"data_mode","in":"query","description":"Data retrieval mode. When set to \"facets\", only facet data is returned.\nWhen set to \"products\", only product data is returned. When not specified,\nboth facets and products are returned.\n","required":false,"schema":{"type":"string","enum":["facets","products"]}}},"schemas":{"SearchResponse":{"type":"object","description":"Search results with products, facets, and pagination","required":["pagination","facets","sorters","search_text","products"],"properties":{"pagination":{"type":"object","description":"Pagination information","required":["current_page","num_pages","page_size","total_count"],"properties":{"current_page":{"type":"integer","description":"Current page number (1-indexed)"},"num_pages":{"type":"integer","description":"Total number of pages"},"page_size":{"type":"integer","description":"Number of items per page"},"total_count":{"type":"integer","description":"Total number of matching products"}}},"facets":{"type":"array","description":"Available filter facets/widgets for filtering search results. Each facet\nrepresents a filterable attribute (e.g., categories, price, color, size).\nFacets are configured through `FacetConfiguration` database records which\ndetermine widget type, display options, and aggregation settings.\nFacets are retrieved from Elasticsearch before product results and\nconverted to widgets based on their configuration.\n","items":{"$ref":"#/components/schemas/Widget"}},"sorters":{"type":"array","description":"Available sorting options for search results. Sort options are configured\nthrough `SortOption` database records which define display labels,\nparameter values, and Elasticsearch sort configurations. Only visible\nsort options are included, ordered by default status and custom order.\nThe currently selected sort option is marked with `is_selected: true`.\n","items":{"$ref":"#/components/schemas/Sorter"}},"search_text":{"type":["string","null"],"description":"The search query text used, or null if no search text was provided"},"products":{"type":"array","description":"Matching products","items":{"$ref":"#/components/schemas/Product"}}}},"Widget":{"type":"object","description":"Filter facet widget representing a filterable attribute in the search interface.\nWidgets are created during the facet conversion process after Elasticsearch\nreturns facet field data. The widget structure and behavior are controlled by\n`FacetConfiguration` database records managed via the administration interface.\n\n**Widget Type Determination:**\n- If a `FacetConfiguration` exists for the attribute, it specifies the widget type,\n  aggregation settings, and display options (name, order, widget_kwargs)\n- If no `FacetConfiguration` exists, fallback rules apply:\n  - `category_ids` always uses Category Widget\n  - `basket_offer_ids` always uses Promotion Widget\n  - All other attributes default to Multi Select Widget\n\n**Facet Configuration Properties:**\n- Widget type (multiselect, category, range, attribute_value, visual_swatch, etc.)\n- Widget kwargs (labels, sorting mode, display options)\n- Facet type and aggregation settings\n- Custom settings and display order\n- Translatable name and widget_kwargs for multi-language support\n\nFacet fields are retrieved from Elasticsearch first, before product results.\nThe facet field size (number of choices) is determined as follows:\n- If facet field has a `FacetConfiguration`, uses configured size from facet_kwargs\n- If attribute key is \"category_ids\", size is set to 500\n- Otherwise, default size is 100\n\nFacet fields are returned with inventory strategy context, as prices and\navailability may vary by inventory strategy. For multi-inventory scenarios,\nprice-related facets automatically adapt to show the active price list.\n","required":["name","key","search_key","widget_type","extra_params","data"],"properties":{"name":{"type":"string","description":"Display name of the facet shown to users"},"key":{"type":"string","description":"Facet key identifier used internally"},"search_key":{"type":"string","description":"Search parameter key used in query strings"},"widget_type":{"type":"string","description":"Widget type identifier. Determines how the filter is rendered in the UI.\nCommon types: \"category\", \"multiselect\", \"range\", \"promotion\"\n","enum":["category","multiselect","range","promotion"]},"order":{"type":["integer","null"],"description":"Display order for the widget. Lower numbers appear first. Null indicates\ndefault ordering based on attribute configuration\n"},"extra_params":{"type":"object","description":"Additional widget parameters for custom widget behavior. Used by\nFacet Configuration to pass widget-specific settings\n","additionalProperties":true},"data":{"type":"object","description":"Widget data including available choices or range values","required":["widget_type","name","key","search_key"],"properties":{"widget_type":{"type":"string","description":"Widget type identifier"},"name":{"type":"string","description":"Display name"},"key":{"type":"string","description":"Facet key identifier"},"search_key":{"type":"string","description":"Search parameter key"},"choices":{"type":"array","description":"Available filter choices (for multiselect and category widgets)","items":{"$ref":"#/components/schemas/WidgetChoice"}},"quantity":{"type":"integer","description":"Total number of matching products for this facet (for range widgets)"},"min_value":{"type":"number","description":"Minimum value in the range (for range widgets)"},"max_value":{"type":"number","description":"Maximum value in the range (for range widgets)"},"step":{"type":"number","description":"Step value for range slider (for range widgets)"},"order":{"type":["integer","null"],"description":"Display order"}},"additionalProperties":true}}},"WidgetChoice":{"type":"object","description":"Individual choice within a filter widget","required":["label","value","quantity","is_selected"],"properties":{"label":{"type":"string","description":"Display label for the choice"},"value":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"Choice value to use in filter requests"},"quantity":{"type":"integer","description":"Number of products matching this choice"},"is_selected":{"type":"boolean","description":"Whether this choice is currently active in the sorting"},"depth":{"type":"integer","description":"Category depth level (for category widgets)"},"real_depth":{"type":"integer","description":"Actual category depth in hierarchy (for category widgets)"},"url":{"type":"string","description":"URL to apply this filter (for category widgets)"},"menuitemmodel":{"type":["string","null"],"description":"Menu item model identifier (for category widgets)"},"is_parent_of_selection":{"type":"boolean","description":"Whether this category is a parent of a selected category (for category widgets)"}}},"Sorter":{"type":"object","description":"Sorting option available for search results. Sort options are configured\nthrough the `SortOption` database model and managed via the administration\ninterface.\n\nEach sort option defines:\n- Display label (translatable for multi-language support)\n- Parameter value used in the `sorter` query parameter\n- Elasticsearch sort configuration (field paths, directions, nested queries)\n- Display order and visibility settings\n- Default status\n\nSort options are retrieved based on the current language and filtered to\nshow only visible options, ordered by default status and custom order.\nWhen a sort option is selected, its Elasticsearch configuration is applied\nto the search query. Sort options automatically adapt to inventory strategy\ncontext, adjusting price field references when multiple price lists are\nactive (e.g., `products.price_1234` instead of `products.price`).\nA secondary sort by product listing ID ensures consistent ordering across pages.\n","required":["label","value","is_selected"],"properties":{"label":{"type":"string","description":"Display label for the sort option. Retrieved from the `SortOption` model\nand supports translation for multi-language sites\n"},"value":{"type":"string","description":"Sort option value to use in the `sorter` query parameter. This value\ncorresponds to the `value` field in the `SortOption` model\n"},"is_selected":{"type":"boolean","description":"Whether this sort option is currently active based on the `sorter` query\nparameter. Only one sort option should be selected at a time\n"}}},"Product":{"type":"object","description":"Product data returned in search results","required":["pk","name","sku","price","in_stock","currency_type","product_type"],"properties":{"pk":{"type":"integer","description":"Product identifier"},"name":{"type":"string","description":"Product name"},"sku":{"type":"string","description":"Product SKU"},"base_code":{"type":["string","null"],"description":"Product base code"},"attributes":{"type":"object","description":"Product attributes as key-value pairs","additionalProperties":true},"attribute_set":{"type":"integer","description":"Attribute set identifier"},"attributes_kwargs":{"type":"object","description":"Attribute metadata including labels and data types","additionalProperties":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"data_type":{"type":"string"}}}},"extra_attributes":{"type":"object","description":"Additional product attributes","additionalProperties":true},"productimage_set":{"type":"array","description":"Product images","items":{"$ref":"#/components/schemas/ProductImage"}},"price":{"type":"string","description":"Product price as stringified decimal"},"in_stock":{"type":"boolean","description":"Stock availability status"},"currency_type":{"type":"string","description":"Currency code"},"retail_price":{"type":"string","description":"Retail price as stringified decimal"},"unit_type":{"type":"string","description":"Stock unit type"},"tax_rate":{"type":"string","description":"Tax rate as stringified decimal"},"absolute_url":{"type":"string","description":"Product detail page URL"},"productvideo_set":{"type":"array","description":"Product videos","items":{"type":"object","additionalProperties":true}},"product_type":{"type":"string","description":"Product type identifier"},"price_type":{"type":"string","description":"Price type"},"form_schema":{"type":["array","null"],"description":"Form schema for product configuration","items":{"type":"object","additionalProperties":true}},"is_ready_to_basket":{"type":"boolean","description":"Whether product can be added to basket"},"stock":{"type":"integer","description":"Available stock quantity"},"data_source":{"type":["object","null"],"description":"Data source information","additionalProperties":true},"basket_offers":{"type":"array","description":"Applicable basket offers/promotions. When `OFFER_SHOW_LISTING_KWARGS` is\nenabled and the offer condition type is QUANTITY, `listing_kwargs` contains\ndiscounted pricing information for display on product listing pages.\n","items":{"type":"object","properties":{"pk":{"type":"integer","description":"Basket offer identifier"},"label":{"type":"string","description":"Display label for the offer"},"listing_kwargs":{"type":"object","description":"Listing arguments containing discounted price information. Only populated\nwhen `OFFER_SHOW_LISTING_KWARGS` is enabled and the offer has a QUANTITY\ncondition type with matching product collection. Contains:\n- `quantity`: Required quantity to qualify for the offer\n- `discounted_total_price`: Total price after discount for the specified quantity\n- `discount`: Discount amount applied\n- `data_sources`: (optional) Data source filters if applicable\n","properties":{"quantity":{"type":"integer","description":"Required quantity to qualify for the offer"},"discounted_total_price":{"type":"string","description":"Total price after discount for the specified quantity"},"discount":{"type":"string","description":"Discount amount applied"},"data_sources":{"type":"array","description":"Data source identifiers (optional, only if condition includes data_sources)","items":{"type":"integer"}}},"additionalProperties":true},"kwargs":{"type":"object","description":"Additional offer configuration parameters","additionalProperties":true},"client_types":{"type":"array","description":"Client types this offer applies to","items":{"type":"string"}}},"additionalProperties":true}},"extra_data":{"type":"object","description":"Additional product data including variants. The structure of this field\ncan be extended by registered plugins. When the `products.listable_product_variants`\nplugin is active and configured, the `variants` array is populated with\nvariant information based on the plugin configuration.\n\n**Plugin Configuration:**\n- When plugins are inactive or not configured, `variants` is an empty array\n- When the `products.listable_product_variants` plugin is active, `variants`\n  contains variant groups based on the configured `attribute_keys` (e.g., \"size\",\n  \"color\")\n- The `product_field_names` setting in the plugin configuration determines\n  which fields are included in variant product objects\n\nFor more information about plugins and their configuration, see:\n[Commerce Plugins Documentation](https://docs.akinon.com/technical-guides/commerce/plugins)\n","properties":{"variants":{"type":"array","description":"Product variants grouped by attribute keys. When the\n`products.listable_product_variants` plugin is active, this array contains\nvariant groups for each configured attribute key. Each group contains options\nwith variant product details based on the plugin's `product_field_names`\nconfiguration.\n\n**Without Plugin:**\n- Returns an empty array: `[]`\n\n**With Plugin Active:**\n- Returns variant groups for each configured attribute key\n- Each group contains options with variant product information\n- Product fields included depend on the plugin's `product_field_names` setting\n","items":{"type":"object","properties":{"attribute_key":{"type":"string","description":"The attribute key that defines this variant group (e.g., \"size\", \"color\").\nOnly present when the `products.listable_product_variants` plugin is\nactive and this attribute key is configured in the plugin's `attribute_keys`.\n"},"options":{"type":"array","description":"Array of variant options for this attribute key. Each option represents\na variant product with the corresponding attribute value. The fields\nincluded in each option's `product` object depend on the plugin's\n`product_field_names` configuration (e.g., pk, price, absolute_url,\nproductimage_set, attributes).\n","items":{"type":"object","properties":{"label":{"type":"string","description":"Display label for the variant option (attribute value)"},"product":{"type":"object","description":"Variant product data. Fields included depend on the plugin's\n`product_field_names` configuration. Common fields include:\n- `pk`: Product identifier\n- `sku`: Product SKU\n- `price`: Product price\n- `retail_price`: Retail price\n- `absolute_url`: Product detail page URL\n- `productimage_set`: Product images\n- `attributes`: Product attributes\n","additionalProperties":true},"in_stock":{"type":"boolean","description":"Stock availability for this variant"},"is_selectable":{"type":"boolean","description":"Whether this variant option can be selected"}},"additionalProperties":true}}},"additionalProperties":true}}},"additionalProperties":true},"is_listable":{"type":"boolean","description":"Whether product is listable"},"listing_code":{"type":["string","null"],"description":"Product listing code"},"price_extra_field":{"type":"object","description":"Additional price field data","additionalProperties":true},"discount_amount":{"type":"number","description":"Discount amount"},"discount_ratio":{"type":"number","description":"Discount ratio"}},"additionalProperties":true},"ProductImage":{"type":"object","description":"Product image metadata","required":["pk","status","image","order","created_date"],"properties":{"pk":{"type":"integer","description":"Image identifier"},"status":{"type":"string","description":"Image status"},"image":{"type":"string","format":"uri","description":"Image URL"},"order":{"type":"integer","description":"Display order"},"created_date":{"type":"string","format":"date-time","description":"Image creation timestamp"},"specialimage_set":{"type":"array","description":"Special images associated with this image","items":{"type":"object","additionalProperties":true}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.akinon.com/commerce-openapis/search/search.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.