getDiscountsByVectorSearch

Semantic (vector) search for discounts.

Description

This method performs a semantic (vector) search for discounts from a natural-language query - it matches on meaning rather than exact keywords. It returns a Promise that resolves to an IDiscountsResponse object - a container with items (the discounts) and total.

Discounts.getDiscountsByVectorSearch(

body*, langCode, offset, limit

);

Parameters schema

Schema

body(required): IDiscountsVectorSearch
Vector search body
example:

{ queryText: "winter sale" }

body.queryText(required): string
Natural-language search query.
example: "winter sale"

body.vectorDistanceThreshold: number
Override of the cosine distance threshold (0..2).
example: 0.3

body.maxHits: number
Top-K candidates fetched before pagination. Default: 100. Max: 500.
example: 10

body.debug: boolean
When true, each returned item gets a distance field.
example: false

langCode: string
Language code. Default: "en_US"
example: "en_US"

offset: number
Parameter for pagination. Default: 0
example: 0

limit: number
Parameter for pagination. Default: 30
example: 30

Examples

Minimal example

const response = await Discounts.getDiscountsByVectorSearch({ queryText: 'winter sale' });

Example with attributes

const response = await Discounts.getDiscountsByVectorSearch(
  {
    queryText: 'winter sale',
    vectorDistanceThreshold: 0.3,
    maxHits: 50,
    debug: true,
  },
  'en_US',
  0,
  30,
);

Example response

{
  "items": [
    {
      "id": 1,
      "type": "DISCOUNT",
      "attributeSetId": 31,
      "conditionLogic": "AND",
      "discountValue": {
        "value": 10,
        "maxAmount": 5,
        "discountType": "FIXED_AMOUNT",
        "applicability": "TO_PRODUCT"
      },
      "exclusions": null,
      "gifts": null,
      "giftsReplaceCartItems": false,
      "userGroups": null,
      "userExclusions": null,
      "localizeInfos": {
        "title": "Example discount"
      },
      "version": 0,
      "identifier": "example_discount",
      "startDate": "2026-03-14T14:55:19.928Z",
      "endDate": "2026-07-31T13:55:24.647Z",
      "attributeValues": {
        "example_discount": {
          "type": "string",
          "value": "test value",
          "isIcon": false,
          "position": 0,
          "additionalFields": {},
          "isProductPreview": false
        }
      },
      "conditions": [],
      "bonusEvent": null,
      "position": 1
    }
  ],
  "total": 1
}

Response schema

Schema: IDiscountsResponse

items: IDiscountsEntity[]
Array of discount entities.

items.id: number
The unique identifier of the discount.

items.attributeSetId: number | null
The identifier of the attribute set linked to the discount, or null when no set is linked.

items.localizeInfos: ILocalizeInfo
The name of the discount.

items.version: number
The version of the discount.

items.identifier: string
The identifier of the discount.

items.type: IDiscountType
The type of the discount.

items.startDate: string
The start date of the discount.

items.endDate: string
The end date of the discount.

items.discountValue: IDiscountValue
The value of the discount, including its type and amount limits.

items.conditionLogic: string
The logic of the discount. Possible values are "AND" | "OR".

items.conditions: IDiscountCondition[]
The conditions of the discount.

items.exclusions: Record<string, unknown> | null
The exclusions of the discount.

items.gifts: Record<string, unknown> | null
The gifts of the discount.

items.giftsReplaceCartItems: boolean
Whether the gifts replace cart items.

items.userGroups: Record<string, unknown> | null
The user groups of the discount.

items.userExclusions: Record<string, unknown> | null
The user exclusions of the discount.

items.attributeValues: IAttributeValues
The attribute values of the discount.

items.attributeSetIdentifier: string
The identifier of the attribute set.

items.bonusEvent: Record<string, unknown>
Bonus event configuration.

items.position: number
Position number for sorting.
example: 1

items.total: number | string
Total count of related entries.
example: "1"

items.distance: number
Cosine distance to the query. Returned only by the semantic (vector) search endpoint when debug: true is passed in the search body.
example: 0.12

total: number
Total number of discounts.

ℹ️ Semantic search matches on meaning, not on the literal text. For keyword matching across every entity type at once use globalSearch().

---