getOrdersByVectorSearch

Semantic (vector) search for the current user's orders. 🔐 This method requires .

Description

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

.getOrdersByVectorSearch(

, , ,

);

Parameters schema

Schema

body(required): IOrdersVectorSearch
Vector search body
example:

{ queryText: "winter jacket" }

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

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 Orders.getOrdersByVectorSearch({ queryText: 'winter jacket' });

Example with attributes

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

Example response

{
  "items": [],
  "total": 0
}

Response schema

Schema: IOrdersByMarkerEntity

items: IOrderByMarkerEntity[]
Array of order storage objects.
example:

[
  {
    "id": 55,
    "storageId": 1,
    "createdDate": "2025-03-22T21:12:42.371Z",
    "statusIdentifier": "inProgress",
    "formIdentifier": "orderForm",
    "formData": [
      {
        "marker": "order_name",
        "value": "Ivan",
        "type": "string"
      }
    ],
    "attributeSetIdentifier": "order_form",
    "totalSum": "300.00",
    "currency": "",
    "paymentAccountIdentifier": "cash",
    "paymentAccountLocalizeInfos": {
      "title": "Cash"
    },
    "products": [
      {
        "id": 2957,
        "title": "Cosmo",
        "sku": null,
        "previewImage": null,
        "price": 150,
        "quantity": 2
      }
    ],
    "isCompleted": false
  }
]

items.id: number
Object identifier.
example: 125

items.storageId: number
Identifier of the order storage object.
example: 1

items.createdDate: string
Date when the order was created.
example: "2023-10-01T12:00:00Z"

items.statusIdentifier: string
Text identifier of the order status.
example: "order-status-1"

items.formIdentifier: string
Text identifier of the form.
example: "bar-orders-form"

items.formData: IOrdersFormData[]
Data submitted by the form linked to the order store.
example:

[
  {
    "marker": "order_name",
    "value": "Ivan",
    "type": "string"
  }
]

items.attributeSetIdentifier: string | null
Text identifier of the attribute set.
example: "attribute-set-1"

items.totalSum: string
Total order amount.
example: "100.00"

items.totalSumRaw: string
Raw total order amount with full precision.
example: "100.00"

items.currency: string
Currency used to pay for the order.
example: "USD"

items.paymentAccountIdentifier: string | null
Textual identifier for the order payment.
example: "payment-1"

items.paymentAccountLocalizeInfos: ILocalizeInfo
Payment account name considering localization.
example:

{
  "title": "Cash"
}

items.products: IOrderProducts[]
Array of products added to order.
example:

[
  {
    "id": 1,
    "name": "Product 1",
    "quantity": 2
  }
]

items.paymentUrl: string | null
Payment link.
example: "https://example.com/pay/123"

items.isCompleted: boolean | null
Indicates that the order has been completed.
example: true

items.isPartial: boolean | null
Indicates that the order is partially paid; null on older orders where it was not tracked.
example: false

items.paymentStrategy: string
Payment strategy of the order.
example: "once"

items.statusLocalizeInfos: ILocalizeInfo
Localized status name.

items.fulfillmentStatusIdentifier: string | null
Text identifier of the fulfillment (delivery) status; null while no fulfillment status is assigned.
example: "shipped"

items.fulfillmentStatusLocalizeInfos: ILocalizeInfo | null
Localized fulfillment status name; null while no fulfillment status is assigned.

items.paymentStatusIdentifier: string | null
Text identifier of the payment status; null while no payment status is assigned.
example: "inProgress-payment"

items.paymentStatusLocalizeInfos: ILocalizeInfo | null
Localized payment status name; null while no payment status is assigned.

items.discountConfig: IOrderDiscountConfig | null
Resolved discount configuration applied to the order (orderDiscounts, productDiscounts, coupon, settings, bonus, totals); null on older orders without a resolved discount config.

items.split: IOrderSplit
Split (staged) payment configuration; present on the by-id order endpoint.

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 found records.
example: 100

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

---