> ## Documentation Index
> Fetch the complete documentation index at: https://help.experro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Perform an advanced product search across your eCommerce catalog using keywords, category/collection filters, facets, and logical filter groups. Supports pagination, sorting, merchandising bypass, and optional inclusion of field metadata and counts.

Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl).


## OpenAPI

````yaml POST /apis/ecommerce-service/public/discovery/v2/search
openapi: 3.1.0
info:
  title: OpenAPI Plant Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://apis.experro.app
    description: Admin Server
  - url: https://{base-address}
    description: Custom Server
    variables:
      base-address:
        default: ''
        description: Enter your custom domain or server address.
security:
  - bearerAuth: []
paths:
  /apis/ecommerce-service/public/discovery/v2/search:
    post:
      summary: Execute Product Search
      description: >-
        Perform an advanced product search across your eCommerce catalog using
        keywords, category/collection filters, facets, and logical filter
        groups. Supports pagination, sorting, merchandising bypass, and optional
        inclusion of field metadata and counts.
      parameters:
        - $ref: '#/components/parameters/CustomerGroupIdHeader'
        - $ref: '#/components/parameters/EcommProviderHeader'
        - $ref: '#/components/parameters/FieldsQryPrm'
        - $ref: '#/components/parameters/LocaleQryPrm'
        - $ref: '#/components/parameters/StoreIdQryPrm'
        - $ref: '#/components/parameters/ChannelIdQryPrm'
        - name: location_id
          in: query
          description: >-
            Identifier for the regional location from the BigCommerce admin
            panel.
          schema:
            type: string
        - $ref: '#/components/parameters/CurrencyQryPrm'
        - name: include_fields_meta
          in: query
          description: >-
            Whether to include metadata about the fields in the response. If
            `true`, include metadata for each searchable field.
          schema:
            type: boolean
        - name: include_count
          in: query
          description: >-
            Flag to include count in response. When `true`, returns total hit
            count alongside items.
          required: false
          schema:
            type: boolean
        - $ref: '#/components/parameters/SkipQryPrm'
        - $ref: '#/components/parameters/LimitQryPrm'
        - name: sort_order
          in: query
          schema:
            type: string
          description: >-
            Order of sorting results (`asc` for ascending, `desc` for
            descending)
        - name: sort_by
          in: query
          schema:
            type: string
          description: Field to sort results by (e.g. `price`, `popularity`).
        - name: by_pass_merchandising
          in: query
          schema:
            type: boolean
          description: >-
            Whether to bypass merchandising rules for search. Set to `true` to
            ignore merchandising rules in ranking.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                search_term:
                  type: string
                  description: >-
                    Keyword or phrase to search across product titles and
                    descriptions.
                category_id:
                  type: string
                  description: Identifier for the product category to filter results
                category_name:
                  type: string
                  description: Name of the product category to filter results
                collection_id:
                  type: string
                  description: Identifier for a specific collection or campaign
                facets:
                  type: array
                  description: >-
                    Facet fields with value to filter product by color, size or
                    provided facets
                  items:
                    type: object
                    properties:
                      field_internal_name:
                        type: string
                      value:
                        type: string
                    required:
                      - field_internal_name
                      - value
                filter:
                  type: array
                  description: Query filter expression to narrow results
                  items:
                    type: object
                    properties:
                      group:
                        type: object
                        properties:
                          operator:
                            type: string
                            description: Logical operator to combine rules.
                          rules:
                            type: array
                            description: List of comparison rules.
                            items:
                              type: object
                              properties:
                                action:
                                  type: string
                                field_name:
                                  type: string
                                value:
                                  type: string
                              required:
                                - action
                                - field_name
                                - value
                        required:
                          - operator
                          - rules
                    required:
                      - group
                out_of_stock:
                  type: string
                  description: >-
                    Controls inclusion of out-of-stock items. Whether to
                    include/ exclude/ bury out-of-stock items
                  enum:
                    - INCLUDE
                    - EXCLUDE
                    - BURY
                session_id:
                  type: string
                  description: Identifier for the user's session id
                user_id:
                  type: string
                  description: Unique identifier for the user ID or user email
      responses:
        '200':
          description: Search results with product list and metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad Request – invalid parameters or malformed request body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Status:
                    type: string
                    example: failure
                  Data:
                    $ref: '#/components/schemas/Error404'
        '401':
          description: Unauthorized – Missing or invalid API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Status:
                    type: string
                    example: failure
                  Data:
                    $ref: '#/components/schemas/Error401'
        '500':
          description: Internal Server Error – an unexpected error on the server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Status:
                    type: string
                    example: failure
                  Data:
                    $ref: '#/components/schemas/Error500'
      security: []
      servers:
        - url: https://{base-address}
          description: Custom Server
          variables:
            base-address:
              default: ''
              description: Enter your custom domain or server address.
components:
  parameters:
    CustomerGroupIdHeader:
      name: x-customer-group-id
      in: header
      required: false
      schema:
        type: string
      description: Optional customer group identifier for segment-specific responses.
    EcommProviderHeader:
      name: x-ecomm-provider
      in: header
      required: false
      schema:
        type: string
      description: >-
        eCommerce provider for contextualizing the API call (e.g., shopify,
        magento, etc.).
    FieldsQryPrm:
      name: fields
      in: query
      description: Comma-separated list of fields to include in the response
      schema:
        type: string
      required: true
    LocaleQryPrm:
      name: locale
      in: query
      description: Specifies the language or region for the response data
      required: true
      schema:
        type: string
    StoreIdQryPrm:
      name: store_id
      in: query
      description: Identifier of the store within the eCommerce platform.
      required: false
      schema:
        type: string
    ChannelIdQryPrm:
      name: channel_id
      in: query
      description: Sales or distribution channel identifier.
      required: false
      schema:
        type: string
    CurrencyQryPrm:
      name: currency
      in: query
      description: Currency code for price displays.
      required: false
      schema:
        type: string
    SkipQryPrm:
      name: skip
      in: query
      schema:
        type: integer
      description: Number of items to skip for pagination offset.
    LimitQryPrm:
      name: limit
      in: query
      schema:
        type: integer
      description: Maximum number of items to return.
  schemas:
    SearchResponse:
      type: object
      properties:
        Status:
          type: string
          example: success
        Data:
          type: object
          properties:
            records:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  content_model_id:
                    type: string
                  variant_skus:
                    type: array
                    items:
                      type: string
                  images:
                    type: string
                    description: Stringified JSON array of image objects
                  profit_percentage:
                    type: number
                  conversion_rate:
                    type: number
                  click_rate:
                    type: number
                  revenue:
                    type: number
                  categories:
                    type: array
                    items:
                      type: string
                  brand:
                    type: string
                  sku:
                    type: string
                  name:
                    type: string
                  description:
                    type: string
                  is_featured:
                    type: boolean
                  calculated_price:
                    type: number
                  sku_for_analytics:
                    type: array
                    items:
                      type: string
                  reviews_rating_sum:
                    type: number
                  reviews_count:
                    type: integer
                  variants:
                    type: string
                    description: Stringified JSON array of variant objects
                  sale_price:
                    type: number
                  page_slug:
                    type: string
                  price:
                    type: number
                  brand_page_slug:
                    type: string
                  provider_id:
                    type: string
                  provider_specific_data:
                    type: string
                  variant_options:
                    type: string
                    description: Stringified JSON array of variant option objects
                  retail_price:
                    type: number
                  pin:
                    type: boolean
                  slot:
                    type: boolean
                  include:
                    type: boolean
                  boost:
                    type: boolean
                  is_merchandising:
                    type: boolean
                  position:
                    type: integer
                  rule_details:
                    type: array
                    items:
                      type: object
            meta:
              type: object
              properties:
                STORE_HASH:
                  type: string
                ENV_TYPE:
                  type: string
                TENANT_ID:
                  type: string
                WORKSPACE_ID:
                  type: string
                _fields_:
                  type: object
                  properties:
                    menu_title:
                      type: object
                      properties:
                        type:
                          type: string
                        sub_type:
                          type: string
                        is_array:
                          type: boolean
                        is_searchable:
                          type: boolean
                    menu_description:
                      type: object
                      properties:
                        type:
                          type: string
                        sub_type:
                          type: string
                        is_array:
                          type: boolean
                        is_searchable:
                          type: boolean
                    page_title:
                      type: object
                      properties:
                        type:
                          type: string
                        sub_type:
                          type: string
                        is_array:
                          type: boolean
                        is_searchable:
                          type: boolean
                total_count:
                  type: integer
                is_redirects:
                  type: boolean
                redirect_url:
                  type: string
                did_you_mean:
                  type: string
    Error404:
      type: object
      properties:
        Status:
          type: string
          example: failure
        Error:
          type: object
          properties:
            message:
              type: string
            name:
              type: string
            code:
              type: string
          required:
            - message
            - name
      required:
        - Status
        - Error
    Error401:
      type: object
      properties:
        Status:
          type: string
          example: failure
        Error:
          type: object
          properties:
            message:
              type: string
            name:
              type: string
            code:
              type: string
          required:
            - message
            - name
      required:
        - Status
        - Error
    Error500:
      type: object
      properties:
        Status:
          type: string
          example: failure
        Error:
          type: object
          properties:
            message:
              type: string
            name:
              type: string
            code:
              type: string
          required:
            - message
            - name
      required:
        - Status
        - Error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````