getRelatedProductsById
Search for all related product objects by product ID.
Description
Fetches the products related to the product with the given id. The optional userQuery takes pagination and sorting (offset, limit, sortOrder, sortKey), statusMarker, templateMarker, relationMode and signPrice. Resolves to an IProductsResponse: the products are in items, the total count in total.
.getRelatedProductsById(
,
,
);
Parameters schema
Schema
id: number
ID of the product to find related products for.
example: 12345
langCode: string
Language code. Default: the langCode passed to defineOneEntry ("en_US" if none).
example: "en_US"
userQuery: IProductsRelatedQuery
Optional query parameters.
example:
{
"limit": 30,
"offset": 0,
"sortOrder": "DESC",
"sortKey": "id",
"signPrice": "orders",
"statusMarker": "in_stock",
"templateMarker": "template_12345"
}
userQuery.offset(required): number
Number of records to skip. Default: 0. offset + limit must not exceed 200; a larger window is rejected with 400.
userQuery.limit(required): number
Maximum number of records to return. Default: 30.
userQuery.sortOrder(required): string
Sort order: "DESC" or "ASC". Default: "DESC".
userQuery.sortKey(required): string
Field to sort by: "id", "position", "title", "date", "price" or "status". Default: "position".
userQuery.signPrice: string
Marker of the order storage to fix prices for. When set, each product comes with a signedPrice that holds the price for a limited time.
see: Fixing the price
userQuery.statusMarker: string | null
Marker of the product status. Default: null.
example: "in_stock"
userQuery.templateMarker: string | null
Marker of the product template. Default: null.
example: "template_12345"
userQuery.relationMode: string
How relations are computed: "global" (the default) runs the template's chain of conditions as is; "local" additionally requires the attribute value of the product id to satisfy the template condition (same operator, same stored operand) before the products of that step are kept.
example: "local"
Record limit. If the user group's permission for this method allows only restricted reading, the API returns at most the number of records set in the project settings (10 by default), whatever limit you pass. With full read access, limit works as usual. See Module permissions (opens in a new tab).
signPricelocks the returned price for a limited time. Set it to your order storage marker. See Fixing the price (signPrice).
Examples
Minimal example
const response = await Products.getRelatedProductsById(2954);
Example with userQuery
const = { "offset": 0, "limit": 30, "sortOrder": "DESC", "sortKey": "id"};
const response = await Products.getRelatedProductsById(2954, 'en_US', userQuery);
Example response
The example shows the shape of one item, as returned by getProducts().
{
"total": 1,
"items": [
{
"id": 2954,
"localizeInfos": {
"title": "Box"
},
"isVisible": true,
"isSync": false,
"sku": null,
"price": 51,
"additional": {
"prices": {
"min": 51,
"max": 180
}
},
"categories": [
"catalog"
],
"statusIdentifier": "sale",
"statusLocalizeInfos": {
"title": "Sale"
},
"templateIdentifier": null,
"shortDescTemplateIdentifier": "product_preview",
"attributeValues": {
"product-name": {
"type": "string",
"value": "product-name",
"isIcon": false,
"position": 0,
"additionalFields": {},
"isProductPreview": false
},
"price": {
"type": "integer",
"value": 51,
"isIcon": false,
"position": 1,
"additionalFields": {},
"isProductPreview": false
},
"currency_products": {
"type": "string",
"value": "usd",
"isIcon": false,
"position": 2,
"additionalFields": {},
"isProductPreview": false
}
},
"attributeSetIdentifier": "products",
"isPositionLocked": false,
"position": 1,
"rating": {},
"paymentStages": null,
"moduleFormConfigs": [
{
"id": 12,
"formIdentifier": "review",
"moduleIdentifier": "catalog",
"isGlobal": false,
"isClosed": false,
"isModerate": false,
"viewOnlyMyData": false,
"commentOnlyMyData": false,
"entityIdentifiers": [
{
"id": "catalog",
"isNested": true
}
],
"formDataCount": 823,
"ratingCalculation": "average",
"allowHalfRatings": null,
"maxRatingScale": null,
"isAnonymous": null,
"allowRerating": null,
"isRating": null,
"entityFormDataCount": {
"2954": 823
},
"nestedEntityIdentifiers": [
"catalog"
],
"exceptionIds": []
}
],
"discountConfig": {}
}
]
}
Response schema
Schema: IProductsResponse
total: number
Total number of products found.
example: 100
items: IProductsEntity[]
Products in this response.
example:
[
{
"id": 12345,
"title": "Product 1"
},
{
"id": 67890,
"title": "Product 2"
}
]
items.id: number
ID of the product.
example: 12345
items.localizeInfos: ILocalizeInfo
Localized product data, such as the title.
example:
{}
items.statusIdentifier: string | null
Marker of the product status, or null.
example: "in_stock"
items.statusLocalizeInfos: ILocalizeInfo
Localized status name for the product.
example:
{ "title": "Sale" }
items.attributeSetIdentifier: string | null
Marker of the attribute set, or null if none is assigned.
example: "set_12345"
items.position: number
Position used for sorting.
example: 1
items.price: number | null
Product price from the search index.
example: 150.00
items.additional: object
Extra values computed by the search index, such as the price range in prices.min and prices.max.
example:
{
"prices": {
"min": 5,
"max": 150
}
}
items.sku: string | null
Product SKU from the search index, or null.
example: "SKU_12345"
items.isSync: boolean
Whether the product's attribute index is up to date for the requested language. When false, an empty or partial attributeValues means the values are not published yet, not that there are none.
example: true
items.attributeValues: IAttributeValues
Attribute values keyed by attribute marker.
example:
{
"color": {
"type": "string",
"value": "red",
"isIcon": false,
"position": 0,
"additionalFields": {}
}
}
items.categories: string[]
URLs of the catalog pages the product belongs to.
example:
[
"catalog"
]
items.isVisible: boolean
Whether the product is visible.
example: true
items.moduleFormConfigs: Array<IFormConfig>
Form configurations of the module.
items.rating: IRating
Rating data: average value, likes and dislikes, and the calculation method.
items.isPositionLocked: boolean
Whether the sorting position is locked.
example: false
items.relatedIds: number[]
IDs of related products.
example:
[
12345,
67890
]
items.paymentStages: unknown
Payment stages of the product: an array of { title, value, marker } objects, or null when none are set.
example: null
items.distance: number
Relevance distance in vector (semantic) search. Present only in vector search results.
example: 0.42
items.discountConfig: Record<string, unknown>
Discount configuration.
example:
{}
items.templateIdentifier: string | null
Marker of the linked template.
example: "template_12345"
items.shortDescTemplateIdentifier: string | null
Marker of the template used for the short description.
example: "short_desc_template_12345"
items.signedPrice: string
Signed token (JWT) that fixes the product price for an order. Returned when signPrice is set.
see: Fixed product price
example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
items.productPages: IProductPageRef[]
Links between the product and the catalog pages it belongs to.
example:
[
{
"id": 16,
"pageId": 4,
"productId": 15,
"positionId": 244,
"categoryPath": "products"
}
]
items.blocks: string[]
Markers of the blocks attached to the product.
example:
[
"block_12345",
"block_67890"
]
totalFound: number
Number of products matched before limits are applied; returned by block product endpoints (similarProducts, cart/wishlist recommendations, frequently ordered). Optional.
example: 2
signedPriceis a signed token that carries the locked price. Pass it back when you create an order. See Fixed product price (signedPrice).