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

# Recommendation Widget

> Returns personalized product recommendations for the specified widget based on the provided context (e.g., current product, category, or cart contents). Supports optional filtering and pagination.

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/recommendation/v2/widgets/{widgetId}
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/recommendation/v2/widgets/{widgetId}:
    post:
      summary: Get Recommendations for a Widget Context
      description: >-
        Returns personalized product recommendations for the specified widget
        based on the provided context (e.g., current product, category, or cart
        contents). Supports optional filtering and pagination.
      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: widgetId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the widget to retrieve.
        - 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
        - $ref: '#/components/parameters/SkipQryPrm'
        - $ref: '#/components/parameters/LimitQryPrm'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                context_type:
                  type: string
                  description: >-
                    Specify the type of context for the request (e.g., product,
                    category, web_pages, cart, etc)
                context_data:
                  type: string
                  description: Context-specific data, relevant to the context_type
                product_ids:
                  type: array
                  description: List of product IDs to seed “similar items” recommendations.
                  items:
                    type: string
                category_ids:
                  type: array
                  description: List of category IDs to seed category-based recommendations.
                  items:
                    type: string
                user_id:
                  type: string
                  description: Unique identifier for the user or user email.
                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: Comparison rules to filter items.
                            items:
                              type: object
                              properties:
                                action:
                                  type: string
                                  description: Comparison operation.
                                field_name:
                                  type: string
                                  description: Field on which to apply the rule.
                                value:
                                  type: string
                                  description: Value(s) to compare against.
                              required:
                                - action
                                - field_name
                                - value
                        required:
                          - operator
                          - rules
                    required:
                      - group
      responses:
        '200':
          description: A list of recommended products with optional metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationWidget200Response'
        '400':
          description: Bad Request – missing or invalid context or filter data.
          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:
    RecommendationWidget200Response:
      type: object
      properties:
        Status:
          type: string
          example: success
        Data:
          type: object
          properties:
            records:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  tenant_id:
                    type: string
                  workspace_id:
                    type: string
                  content_model_id:
                    type: string
                  content_model_data_id:
                    type: string
                  version_no:
                    type: integer
                  version_name:
                    type: string
                  language:
                    type: array
                    items:
                      type: string
                  modified_by:
                    type: string
                  modified_at:
                    type: string
                    format: date-time
                  created_by:
                    type: string
                  created_at:
                    type: string
                    format: date-time
                  store_id:
                    type: string
                  channel_id:
                    type: array
                    items:
                      type: string
                  _version_:
                    type: string
                  in_stock:
                    type: integer
                  brand_page_slug:
                    type: string
                  revenue:
                    type: integer
                  category_ids:
                    type: array
                    items:
                      type: string
                  variants_sku_count:
                    type: integer
                  sku_for_analytics:
                    type: array
                    items:
                      type: string
                  provider:
                    type: string
                  provider_id:
                    type: string
                  images:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        product_id:
                          type: string
                        is_thumbnail:
                          type: boolean
                        sort_order:
                          type: integer
                        description:
                          type: string
                        image_file:
                          type: string
                        url_zoom:
                          type: string
                        url_standard:
                          type: string
                        url_thumbnail:
                          type: string
                        url_tiny:
                          type: string
                        date_modified:
                          type: string
                          format: date-time
                  price:
                    type: number
                  description:
                    type: string
                  sku:
                    type: string
                  type:
                    type: string
                  name:
                    type: string
                  page_slug:
                    type: string
                  page_title:
                    type: string
                  menu_title:
                    type: string
                  condition:
                    type: array
                    items:
                      type: string
                  sort_order:
                    type: integer
                  is_price_hidden:
                    type: boolean
                  availability:
                    type: string
                  upc:
                    type: string
                  warranty:
                    type: string
                  is_featured:
                    type: boolean
                  is_visible:
                    type: boolean
                  is_free_shipping:
                    type: boolean
                  fixed_cost_shipping_price:
                    type: number
                  inventory_tracking:
                    type: string
                  inventory_warning_level:
                    type: integer
                  inventory_level:
                    type: integer
                  brand:
                    type: string
                  brand_id:
                    type: string
                  product_tax_code:
                    type: string
                  tax_class_id:
                    type: string
                  map_price:
                    type: number
                  sale_price:
                    type: number
                  retail_price:
                    type: number
                  cost_price:
                    type: number
                  height:
                    type: number
                  depth:
                    type: number
                  width:
                    type: number
                  weight:
                    type: number
            _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
    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

````