> ## 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.

# Auto Suggest

> Returns search suggestions, category hints, popular/recent queries, content-page matches, and product previews based on a partially typed search term. Supports spell-correction and preview mode.

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/auto-suggest
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/auto-suggest:
    post:
      summary: Fetch Auto-Suggest Data
      description: >-
        Returns search suggestions, category hints, popular/recent queries,
        content-page matches, and product previews based on a partially typed
        search term. Supports spell-correction and preview mode.
      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, returns metadata for each filterable field.
          schema:
            type: boolean
        - name: content_fields
          in: query
          description: Comma-separated list of fields to include for content pages
          schema:
            type: string
      requestBody:
        description: Request body
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                show_auto_suggester_term:
                  type: boolean
                  description: Whether to show the auto-suggester term
                auto_suggester_term_limit:
                  type: integer
                  description: Limit for the number of auto-suggester terms to return.
                show_category:
                  type: boolean
                  description: Whether to show product category name suggestions.
                include_category_count:
                  type: boolean
                  description: Whether to include the number of products per category
                category_limit:
                  type: integer
                  description: Max number of categories to return.
                show_popular_searches:
                  type: boolean
                  description: Whether to Include popular search phrases.
                popular_searches_limit:
                  type: integer
                  description: Max number of popular searches to return.
                show_recent_searches:
                  type: boolean
                  description: Whether to show user’s recent search history.
                recent_searches_limit:
                  type: integer
                  description: Max number of recent searches to return.
                show_content_pages:
                  type: boolean
                  description: Whether to show matching content pages in the result.
                content_pages_limit:
                  type: integer
                  description: Max number of content pages to return.
                show_products:
                  type: boolean
                  description: Whether to show products in the result.
                products_limit:
                  type: integer
                  description: Max number of product suggestions to return.
                search_term:
                  type: string
                  description: Partial search input for which suggestions are requested.
                filter:
                  type: array
                  description: Query filter expression to narrow results
                  items:
                    type: object
                    properties:
                      group:
                        type: object
                        properties:
                          operator:
                            type: string
                            description: Logical operator between rules.
                          rules:
                            type: array
                            description: List of comparison rules.
                            items:
                              type: object
                              properties:
                                action:
                                  type: string
                                  description: Comparison operator.
                                field_name:
                                  type: string
                                  description: Field to filter on.
                                value:
                                  type: string
                                  description: Value to compare.
                is_auto_spellcheck:
                  type: boolean
                  description: Whether to auto-correct misspellings in the search term.
                out_of_stock:
                  type: string
                  description: Whether to include/ exclude/ bury out-of-stock items
                user_id:
                  type: string
                  description: Unique identifier for the user ID or user email.
                session_id:
                  type: string
                  description: Identifier for the user's session id.
                preview:
                  type: boolean
                  description: >-
                    Whether this is a preview mode request. If true, the
                    suggestions returns in preview mode.
      responses:
        '200':
          description: >-
            Auto-suggest payload containing terms, categories, products, pages,
            and more.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoSuggest200Response'
        '400':
          description: Bad Request – missing or invalid parameters.
          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
  schemas:
    AutoSuggest200Response:
      type: object
      properties:
        Status:
          type: string
          example: success
        Data:
          type: object
          properties:
            categories:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  page_slug:
                    type: string
                  product_count:
                    type: integer
                required:
                  - name
                  - page_slug
                  - product_count
            auto_suggester:
              type: array
              items:
                type: string
            popular_searches:
              type: array
              items:
                type: string
            redirect_url:
              type: string
            products:
              $ref: '#/components/schemas/ProductResponse'
            _meta_:
              $ref: '#/components/schemas/MetaResponse'
    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
    ProductResponse:
      type: array
      items:
        type: object
        properties:
          sku:
            type: string
          matched_sku:
            type: string
          position:
            type: integer
          id:
            type: string
          score:
            type: number
            format: float
          variant_skus:
            type: array
            items:
              type: string
          variants:
            type: array
            items:
              type: object
              properties:
                id:
                  type: string
                title:
                  type: string
                price:
                  type: string
                sku:
                  type: string
                position:
                  type: integer
                compare_at_price:
                  type:
                    - string
                    - 'null'
                selected_options:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                inventory_quantity:
                  type: integer
                inventory_policy:
                  type: string
                created_at:
                  type: string
                  format: date-time
                updated_at:
                  type: string
                  format: date-time
                image:
                  type: object
                  properties:
                    id:
                      type: string
                    url:
                      type: string
                      format: uri
                    alt_text:
                      type: string
                inventory_item:
                  type: object
                  properties:
                    measurement:
                      type: object
                      properties:
                        weight:
                          type: object
                          properties:
                            unit:
                              type: string
                            value:
                              type: number
                __parent_id:
                  type: string
                graphql_id:
                  type: string
                image_id:
                  type: string
                weight:
                  type: number
                weight_unit:
                  type: string
          name:
            type: string
          brand:
            type: string
          calculated_price:
            type: number
            format: float
          description:
            type: string
          inventory_level:
            type: integer
          images:
            type: array
            items:
              type: object
              properties:
                id:
                  type: string
                url:
                  type: string
                altText:
                  type: string
                graphql_id:
                  type: string
                src:
                  type: string
          variant_options:
            type: array
            items:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
                position:
                  type: integer
                values:
                  type: array
                  items:
                    type: string
                optionValues:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
          category_meta:
            type: array
            items:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
                provider_id:
                  type: integer
          provider_id:
            type: string
          page_slug:
            type: string
          pin:
            type: boolean
          slot:
            type: boolean
    MetaResponse:
      type: object
      properties:
        tenant_id:
          type: string
        workspace_id:
          type: string
        env_type:
          type: string
        store_hash:
          type: string
        content_model_id:
          type: string
        _fields_:
          type: object
          additionalProperties:
            type: object
            properties:
              type:
                type: string
              sub_type:
                type: string
              is_array:
                type: boolean
              is_searchable:
                type: boolean
            required:
              - type
              - sub_type
              - is_array
              - is_searchable
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````