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

# Get Top Recommendations

> Fetch products by a ranking strategy (bestsellers, new arrivals) with rich criteria filters, full-text query, cursor pagination, and facet aggregations.

## Overview

The **top recommendations** endpoint lets headless storefronts fetch products **without a seed anchor** — unlike `/recommendations` and `/recommendations/automatic`, no `product_ids` are required. It is the right endpoint for:

* Catalog / collection landing pages ("Bestsellers", "New arrivals")
* Search results constrained by a strategy (e.g. bestsellers matching "wireless charger")
* Merchandising widgets that need filtered top-N lists with facet sidebars

The filter contract is **identical to `/recommendations/automatic`** — same `filter` shape, same Joi schema — extended with four additional dimensions (`excluded_tags`, `collections`, `product_types`, `price`). Those extensions are also accepted by the automatic endpoint going forward.

> [!NOTE]
>
> **Authentication.** Pass `Authorization: Bearer <shop storefront token>` and `x-shop: <myshopify domain>` on every call. See [Get Started → Headless Authentication](https://docs.glood.ai/api-reference/recommendations/headless/init.md) for token provisioning.

## Ranking strategies

| Strategy | What it returns |
| - | - |
| `BESTSELLERS` | Products ranked by revenue over the last 7, 15, or 30 days (selectable via `strategy_options.sales_time_period`, default 7). |
| `NEW_ARRIVALS` | Most recently published products. |

## Filter dimensions

`filter` is fully optional. Each sub-field is independently optional and combined as an AND:

* **`tags`** / **`excluded_tags`** — include / exclude by product tag.
* **`vendors`** — vendor names (exact match).
* **`product_types`** — product type values.
* **`collections`** — collection IDs the product must belong to.
* **`price.min`** / **`price.max`** — price range in shop currency.
* **`variants.is_in_stock`**, **`variants.available_for_sale`** — variant-level availability (matches any variant).
* **`variants.options[]`** — variant option matches (e.g. `Color: Black`).
* **`variants.sku[]`** — variant SKU match.
* **`metafields[]`** — match by `{namespace, key, value}`; requires a `filterKey` to exist on the indexed product.

> [!TIP]
>
> **Array or comma-separated string.** The list-style fields `tags`, `excluded_tags`, `vendors`, `product_types`, and `collections` accept **either** a JSON array of strings **or** a single comma-separated string. Useful for clients whose query serializers can't construct arrays from variables. Both forms below are equivalent:
>
> ```json theme={null}
> { "filter": { "tags": ["new", "sale", "featured"] } }
> { "filter": { "tags": "new,sale,featured" } }
> ```
>
> Whitespace around commas is trimmed.

## Text query

When `query` is provided, a `multi_match` clause is added across `title^3`, `description`, `tags`, `vendor`, `productType` with `operator: AND`, `lenient: true`. The **strategy sort still wins** — products matching the text query are ranked by sales (or recency), not by BM25 relevance. For relevance-first text search, use the [AI Search](https://docs.glood.ai/api-reference/search/introduction.md) endpoint instead.

## Facets

Pass `facets: ["vendor", "product_type", "tag", "price"]` (any subset) to receive aggregations alongside the products. Each facet returns top values with counts. The `price` facet returns fixed buckets (`0-50`, `50-100`, `100-250`, `250+`).

Facet counts are computed using a **post-filter** model — each facet's counts ignore that dimension's filter so a sidebar UI can show "all available vendors" even when the user has selected one. Other filters still apply.

## Pagination

Cursor-based, matching the rest of the v3 headless surface. The first request can pass `pagination.limit` (1–100, default 24). Subsequent pages pass the `cursor` returned in the previous response.

> [!WARNING]
>
> When paginating with a `cursor`, the `filter`, `query`, and `strategy` must **stay identical** to the request that produced the cursor — changing them invalidates the sort context and returns incoherent ordering.

The response includes `pagination.total` and `pagination.totalRelation` (`"eq"` or `"gte"`). Elasticsearch caps totals at 10,000 by default — when the relation is `"gte"`, the real total is ≥ that value.

## Examples

```bash Minimal — Bestsellers theme={null}
curl -sS -X POST 'https://storefront.glood.ai/api/storefront/v3/headless/recommendations/top' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <shop-storefront-token>' \
  -H 'x-shop: shop.myshopify.com' \
  -d '{
    "strategy": "BESTSELLERS",
    "view": "product_details"
  }'
```

```bash New Arrivals + text + price filter theme={null}
curl -sS -X POST 'https://storefront.glood.ai/api/storefront/v3/headless/recommendations/top' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <shop-storefront-token>' \
  -H 'x-shop: shop.myshopify.com' \
  -d '{
    "strategy": "NEW_ARRIVALS",
    "view": "product_details",
    "query": "wireless charger",
    "filter": {
      "price": { "min": 20.00, "max": 80.00 },
      "variants": { "is_in_stock": true }
    },
    "facets": ["vendor", "price"],
    "pagination": { "limit": 24 }
  }'
```

```bash Bestsellers — full filter surface theme={null}
curl -sS -X POST 'https://storefront.glood.ai/api/storefront/v3/headless/recommendations/top' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <shop-storefront-token>' \
  -H 'x-shop: shop.myshopify.com' \
  -d '{
    "strategy": "BESTSELLERS",
    "view": "product_details",
    "query": "cable",
    "filter": {
      "tags": ["holiday-2026"],
      "excluded_tags": ["clearance", "discontinued"],
      "vendors": ["UGREEN"],
      "product_types": ["Cable", "Hub"],
      "collections": ["345678901", "456789012"],
      "metafields": [
        { "namespace": "custom", "key": "gender", "value": "unisex" }
      ],
      "variants": {
        "is_in_stock": true,
        "available_for_sale": true,
        "options": [{ "name": "Length", "value": "2m" }]
      },
      "price": { "min": 5.00, "max": 50.00 }
    },
    "facets": ["vendor", "product_type", "tag", "price"],
    "pagination": { "limit": 24 }
  }'
```

```bash Bestsellers — 30-day window theme={null}
curl -sS -X POST 'https://storefront.glood.ai/api/storefront/v3/headless/recommendations/top' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <shop-storefront-token>' \
  -H 'x-shop: shop.myshopify.com' \
  -d '{
    "strategy": "BESTSELLERS",
    "strategy_options": { "sales_time_period": 30 },
    "view": "product_details",
    "filter": { "collections": ["123456789"] },
    "pagination": { "limit": 12 }
  }'
```

```bash Paginate — second page via cursor theme={null}
curl -sS -X POST 'https://storefront.glood.ai/api/storefront/v3/headless/recommendations/top' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <shop-storefront-token>' \
  -H 'x-shop: shop.myshopify.com' \
  -d '{
    "strategy": "BESTSELLERS",
    "view": "product_details",
    "filter": { "price": { "min": 20.00, "max": 80.00 } },
    "pagination": {
      "cursor": "eyJzIjpbMTIzLjQ1LCI5ODc2NTQzMjEiXSwic2Vzc2lvbiI6IjU1ZGE0NjM5LTUyMTYtNGE4Mi1iMmNlLTUxYTU3MmZjMzVjNCJ9",
      "limit": 24
    }
  }'
```

```bash Filter lists as CSV strings theme={null}
curl -sS -X POST 'https://storefront.glood.ai/api/storefront/v3/headless/recommendations/top' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <shop-storefront-token>' \
  -H 'x-shop: shop.myshopify.com' \
  -d '{
    "strategy": "BESTSELLERS",
    "view": "product_details",
    "filter": {
      "tags": "new,sale,featured",
      "excluded_tags": "clearance,discontinued",
      "vendors": "UGREEN,Anker",
      "product_types": "Cable,Hub",
      "collections": "345678901,456789012"
    },
    "pagination": { "limit": 24 }
  }'
```

```bash IDs only (lightweight) theme={null}
curl -sS -X POST 'https://storefront.glood.ai/api/storefront/v3/headless/recommendations/top' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <shop-storefront-token>' \
  -H 'x-shop: shop.myshopify.com' \
  -d '{
    "strategy": "BESTSELLERS",
    "view": "product_ids",
    "pagination": { "limit": 50 }
  }'
```

```bash Edge endpoint theme={null}
curl -sS -X POST 'https://edge.glood.ai/api/edge/storefront/v3/headless/recommendations/top' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <shop-storefront-token>' \
  -H 'x-shop: shop.myshopify.com' \
  -d '{
    "strategy": "BESTSELLERS",
    "view": "product_details",
    "filter": { "variants": { "is_in_stock": true } },
    "facets": ["vendor", "price"],
    "pagination": { "limit": 24 }
  }'
```

Each product carries `trending_rank` and `sales_rank` — shop-wide ranks refreshed daily; see the field reference.

```json 200 theme={null}
{
  "status": "ok",
  "serve_id": "7c3f5e8a-2b14-49c1-a7d3-93f4e2bb1c8e",
  "strategy": "BESTSELLERS",
  "products": [
    {
      "handle": "uno-usb-c-cable-100w",
      "product_id": 8123456789012,
      "title": "Uno USB-C to USB-C Cable 100W",
      "vendor": "UGREEN",
      "product_type": "Cable",
      "tags": "cable, usb-c, fast-charge",
      "price": 9.34,
      "compare_at_price": 14.99,
      "image": {
        "id": "gid://shopify/ImageSource/33459800441029",
        "url": "https://cdn.shopify.com/s/files/.../cable.jpg",
        "altText": null,
        "width": 1600,
        "height": 1600
      },
      "variants": [],
      "options": [],
      "metafields": [],
      "trending_rank": 3,
      "sales_rank": 7
    }
  ],
  "pagination": {
    "cursor": "eyJzIjpbMC44Mzc3LCI4MTIzNDU2Nzg5MDEyIl0sInNlc3Npb24iOiI1NWRhNDYzOS01MjE2LTRhODItYjJjZS01MWE1NzJmYzM1YzQifQ==",
    "hasMore": true,
    "total": 327,
    "totalRelation": "eq",
    "limit": 24
  },
  "facets": {
    "vendor": [
      { "value": "UGREEN", "count": 142 },
      { "value": "Anker",  "count": 98 }
    ],
    "price": [
      { "min": 0,   "max": 50,  "count": 210 },
      { "min": 50,  "max": 100, "count": 78 },
      { "min": 100, "max": 250, "count": 39 }
    ]
  }
}
```

```json 400 theme={null}
{
  "errors": [
    {
      "message": "\"strategy\" is required",
      "path": ["strategy"],
      "type": "any.required",
      "context": { "label": "strategy", "key": "strategy" }
    }
  ]
}
```

```json 401 theme={null}
{
  "error": "Invalid authentication"
}
```

```json 429 theme={null}
{
  "error": "Too many requests, please try again later."
}
```


## OpenAPI

````yaml POST /api/storefront/v3/headless/recommendations/top
openapi: 3.0.1
info:
  title: Glood.AI API Reference
  description: Glood.AI API Reference
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://storefront.glood.ai
security:
  - bearerAuth: []
paths:
  /api/storefront/v3/headless/recommendations/top:
    post:
      description: >-
        Fetch products by a ranking strategy (BESTSELLERS, NEW_ARRIVALS) with
        rich criteria filters, full-text query, cursor pagination, and optional
        facet aggregations. Unlike `/recommendations` and
        `/recommendations/automatic`, this endpoint does not require seed
        `product_ids` — it is the right choice for catalog landing pages, search
        results constrained by a strategy, and merchandising widgets that need
        filtered top-N lists.
      parameters:
        - name: x-shop
          in: header
          description: Shopify store URL
          required: true
          schema:
            type: string
            example: shop.myshopify.com
      requestBody:
        description: Request body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopRecommendationsRequest'
      responses:
        '200':
          description: Top recommendations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopRecommendationsResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomaticRecommendationsError'
components:
  schemas:
    TopRecommendationsRequest:
      type: object
      required:
        - strategy
        - view
      properties:
        strategy:
          type: string
          description: Ranking strategy to apply
          enum:
            - BESTSELLERS
            - NEW_ARRIVALS
        strategy_options:
          type: object
          description: Strategy-specific tuning. Currently only BESTSELLERS uses this.
          properties:
            sales_time_period:
              type: integer
              description: BESTSELLERS only. Sales window in days. Defaults to 7.
              enum:
                - 7
                - 15
                - 30
        view:
          type: string
          description: Response shape for each product entry.
          enum:
            - product_details
            - product_ids
        query:
          type: string
          description: >-
            Optional free-text query. Applied as a multi_match across title,
            description, tags, vendor, and product_type. The strategy sort still
            wins; products matching the text query rank by
            sales/recency/trending score, not BM25.
        filter:
          type: object
          description: >-
            Same filter shape as `/recommendations/automatic`, extended with
            `excluded_tags`, `collections`, `product_types`, and `price`.
          properties:
            variants:
              type: object
              properties:
                options:
                  type: array
                  items:
                    type: object
                    required:
                      - name
                      - value
                    properties:
                      name:
                        type: string
                        description: Option name (e.g. Size, Color)
                      value:
                        type: string
                        description: Option value
                is_in_stock:
                  type: boolean
                  description: Match products with at least one in-stock variant.
                sku:
                  type: array
                  items:
                    type: string
                  description: Match products with at least one of the given SKUs.
                available_for_sale:
                  type: boolean
                  description: Match products with at least one variant available for sale.
            tags:
              type: array
              items:
                type: string
              description: >-
                Include products carrying any of these tags. **Also accepts a
                comma-separated string** (e.g. `"new,sale,featured"`) for
                clients whose serializers can't construct arrays.
            excluded_tags:
              type: array
              items:
                type: string
              description: >-
                Exclude products carrying any of these tags. **Also accepts a
                comma-separated string** (e.g. `"clearance,discontinued"`).
            vendors:
              type: array
              items:
                type: string
              description: >-
                Include products from these vendors. **Also accepts a
                comma-separated string** (e.g. `"UGREEN,Anker"`).
            product_types:
              type: array
              items:
                type: string
              description: >-
                Include products of these product types. **Also accepts a
                comma-separated string** (e.g. `"Cable,Hub"`).
            collections:
              type: array
              items:
                type: string
              description: >-
                Include products belonging to any of these collection IDs.
                **Also accepts a comma-separated string** (e.g.
                `"345678901,456789012"`).
            price:
              type: object
              properties:
                min:
                  type: number
                  description: Minimum price (inclusive).
                max:
                  type: number
                  description: Maximum price (inclusive).
            metafields:
              type: array
              items:
                type: object
                required:
                  - namespace
                  - key
                  - value
                properties:
                  namespace:
                    type: string
                  key:
                    type: string
                  value:
                    type: string
              description: >-
                Match products with these metafield namespace/key/value
                combinations.
        facets:
          type: array
          items:
            type: string
            enum:
              - vendor
              - product_type
              - tag
              - price
          description: >-
            Facet dimensions to return alongside the products. Facets are
            computed only when this array is non-empty.
        pagination:
          type: object
          properties:
            cursor:
              type: string
              description: >-
                Cursor from a previous response. When provided, `filter`,
                `query`, and `strategy` must stay identical to the request that
                produced it.
            limit:
              type: integer
              description: Page size (1-100). Default 24.
              minimum: 1
              maximum: 100
        publication_ids:
          type: array
          items:
            oneOf:
              - type: string
                pattern: ^[0-9]+$
              - type: integer
          maxItems: 50
          description: >-
            Optional. Numeric Shopify publication (sales channel) ids. When
            present, only products published on at least one of these channels
            are returned and the default "published to the Online Store" gate is
            replaced by this filter; market and B2B filters still apply. A
            single id may be sent without the array wrapper. Each id must be one
            the merchant enabled under Settings → Sales channels; unknown ids
            return 400. The id is the numeric tail of
            gid://shopify/Publication/<id>.
          example:
            - '30085840999'
    TopRecommendationsResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - ok
        serve_id:
          type: string
          description: Unique identifier for this serve.
        strategy:
          type: string
          description: Echo of the ranking strategy that produced the results.
        products:
          type: array
          items:
            $ref: '#/components/schemas/HeadlessRecommendedProduct'
        pagination:
          type: object
          properties:
            cursor:
              type: string
              nullable: true
              description: Cursor for the next page. `null` when there are no more pages.
            hasMore:
              type: boolean
              description: Whether more pages exist. Equivalent to `cursor !== null`.
            total:
              type: integer
              description: >-
                Total matching products. Capped at 10,000 by ES default — see
                `totalRelation`.
            totalRelation:
              type: string
              enum:
                - eq
                - gte
              description: Whether `total` is exact (`eq`) or a lower bound (`gte`).
            limit:
              type: integer
        facets:
          type: object
          description: >-
            Present only when the request specified `facets`. Each requested
            dimension is a top-level key.
          additionalProperties:
            type: array
            items:
              type: object
              properties:
                value:
                  type: string
                min:
                  type: number
                max:
                  type: number
                count:
                  type: integer
      example:
        status: ok
        serve_id: 7c3f5e8a-2b14-49c1-a7d3-93f4e2bb1c8e
        strategy: BESTSELLERS
        products:
          - product_id: 8123456789012
            title: Uno USB-C to USB-C Cable 100W
            handle: uno-usb-c-cable-100w
            vendor: UGREEN
            product_type: Cable
            price: 9.34
            compare_at_price: 14.99
            trending_rank: 3
            sales_rank: 7
        pagination:
          cursor: >-
            eyJzIjpbMC44Mzc3LCI4MTIzNDU2Nzg5MDEyIl0sInNlc3Npb24iOiI1NWRhNDYzOS01MjE2LTRhODItYjJjZS01MWE1NzJmYzM1YzQifQ==
          hasMore: true
          total: 327
          totalRelation: eq
          limit: 24
        facets:
          vendor:
            - value: UGREEN
              count: 142
            - value: Anker
              count: 98
          price:
            - min: 0
              max: 50
              count: 210
            - min: 50
              max: 100
              count: 78
            - min: 100
              max: 250
              count: 39
    AutomaticRecommendationsError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: Human readable error message
              path:
                type: array
                items:
                  type: string
                description: Path to the field that caused the error
              type:
                type: string
                description: Type of validation error
              context:
                type: object
                properties:
                  limit:
                    type: number
                    description: Maximum allowed value
                  value:
                    type: number
                    description: Actual value provided
                  label:
                    type: string
                    description: Field label
                  key:
                    type: string
                    description: Field key
    HeadlessRecommendedProduct:
      type: object
      properties:
        product_id:
          type: integer
          description: Shopify product ID
        title:
          type: string
          description: Product title (only when view = product_details)
        handle:
          type: string
          description: Product URL handle (only when view = product_details)
        price:
          type: number
          description: Product price (only when view = product_details)
        compare_at_price:
          type: number
          nullable: true
          description: Original price before discount (only when view = product_details)
        image:
          type: object
          description: Product featured image (only when view = product_details)
          properties:
            id:
              type: string
            url:
              type: string
            altText:
              type: string
              nullable: true
            width:
              type: integer
            height:
              type: integer
        tags:
          type: string
          description: Comma-separated product tags (only when view = product_details)
        options:
          type: array
          description: Product options (only when view = product_details)
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              position:
                type: integer
              values:
                type: array
                items:
                  type: string
        variants:
          type: array
          description: Product variants (only when view = product_details)
          items:
            type: object
            properties:
              variant_id:
                type: integer
                description: Shopify variant ID
              title:
                type: string
              display_name:
                type: string
              price:
                type: string
                description: Price as string with decimals
              compare_at_price:
                type: string
                nullable: true
              sku:
                type: string
              position:
                type: integer
              is_in_stock:
                type: boolean
              available_for_sale:
                type: boolean
              sellable_online_quantity:
                type: integer
              selected_options:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    value:
                      type: string
              image:
                type: object
                nullable: true
                description: Variant image, when the variant has its own
                properties:
                  id:
                    type: string
                  url:
                    type: string
                  altText:
                    type: string
                    nullable: true
                  width:
                    type: integer
                  height:
                    type: integer
        metafields:
          type: array
          description: Product metafields (only when view = product_details)
          items:
            type: object
        product_type:
          type: string
          description: Product type (only when view = product_details)
        vendor:
          type: string
          description: Product vendor (only when view = product_details)
        trending_rank:
          type: integer
          nullable: true
          minimum: 1
          description: >-
            Position among the shop's products by trending score: units sold and
            revenue over the last 30 days, weighted toward recent days and
            adjusted for week-over-week growth — the same score that orders
            trending recommendations. 1 is the top trending product. `null` when
            the product had no sales in the last 30 days. Refreshed daily.
            Shop-wide: `publication_ids` filters which products are returned but
            does not change ranks (recommendations).
        sales_rank:
          type: integer
          nullable: true
          minimum: 1
          description: >-
            Position among the shop's products by revenue over the last 30 days;
            ties go to the product with more units sold. 1 is the top seller.
            `null` when the product had no sales in the last 30 days. Refreshed
            daily. Shop-wide: `publication_ids` filters which products are
            returned but does not change ranks (recommendations).
      description: >-
        A recommended product. With `view: product_ids` only `product_id` is
        present.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.