Server-side integration

Connection stages

1. Basic integration

Rocket Listing integration requires a basic Retail Rocket integration, which includes transferring the product database and configuring user behavior tracking.

Category listing filters require product attributes to be included in the product database transfer.

Basic integration stages

For more information about starting a Retail Rocket integration, see the corresponding section.

Testing requests

Use the interactive API tester in the documentation to test API requests:

• Listing on general pages
• Listing on a category page

2. Configuring server-side interaction

Rocket Listing server-side integration lets you retrieve product listing results directly through the API. It is suitable when full control over how results are displayed is required.

info

• Follow the general integration principles when working with the API;

3. API integration

At this stage, the product is connected to your platform through the server API. The following sections provide detailed integration instructions.

Integration process

Retrieving listing products

Listing on general pages

To retrieve a personalized list of products on general pages, such as the home page, empty cart, or empty search results page, use this method:

GET https://listing.retailrocket.net/catalog/v3/partners/{partnerId}/products

Parameters

Parameter	Type	Required	Description
loadSize	number	Yes	Number of requested products (no more than 300)
linkName	string	Yes	Visitor session name (for example, session); see Session management
linkValue	string	Yes	Visitor session identifier
stockId	string	No	Warehouse identifier for stores using multi-regional support
contentId	string	No	Identifier of the retrieved content, used to request the next batch of content

Response example

{
  "contentId": "61010bd1-4ed1-4fac-9699-3b8ea39d5f00",
  "products": [
    {
      "longProductId": 12345,
      "stringProductId": null
    },
    {
      "longProductId": null,
      "stringProductId": "SKU-67890"
    }
  ]
}

Product identifier format

Depending on the type of product identifiers in your product database, the response contains either longProductId for numeric IDs or stringProductId for string IDs. The other field is null.

---

Listing on a category page

To retrieve a list of products on a category page with filters and sorting, use this method:

POST https://listing.retailrocket.net/category/v2/partners/{partnerId}/products

Parameters

Parameter	Type	Required	Description
categoryId	integer	Yes*	Category identifier (for integration through an XML file)
categoryPath	string	Yes*	Category path (for integration through Product API)
loadSize	number	No	Number of products for infinite scrolling
pageSize	number	No	Number of products per page (for classic pagination)
page	number	No	Requested page number (used with pageSize)
linkName	string	Yes	Visitor session name; see Session management
linkValue	string	Yes	Visitor session identifier; see Session management
stockId	string	No	Warehouse identifier for stores using multi-regional support
sorting	string	No	Sorting option (relevance, popularity)
contentId	string	No	Identifier of the retrieved content, used to request more content (see Pagination)

Sorting parameters

• relevance (By relevance) - sorting based on personalized recommendations adapted to the user's preferences.
• popularity (By popularity) - sorting based on overall product popularity in the store, without accounting for personal preferences.

Specify either categoryId or categoryPath.

Request body

{
  "filters": []
}

Pass an empty filter array in the first request. Filter handling is described in the next section.

Response example

{
  "contentId": "61010bd1-4ed1-4fac-9699-3b8ea39d5f00",
  "products": [
    {
      "longProductId": 12345,
      "stringProductId": null
    },
    {
      "longProductId": 67890,
      "stringProductId": null
    }
  ],
  "filters": [
    {
      "filterId": "brand",
      "title": "Brand",
      "filterType": "checkBoxFilter",
      "values": [
        {
          "valueId": "samsung",
          "valueName": "Samsung",
          "count": 42
        },
        {
          "valueId": "apple",
          "valueName": "Apple",
          "count": 38
        }
      ]
    },
    {
      "filterId": "price",
      "title": "Price",
      "filterType": "intervalFilter",
      "minValue": 1000,
      "maxValue": 150000
    }
  ],
  "sortings": [
    {
      "sortingId": "relevance",
      "sortingName": "By relevance"
    },
    {
      "sortingId": "popularity",
      "sortingName": "By popularity"
    }
  ],
  "selectedSortingId": "relevance"
}

---

Working with filters

Request without selected filters

When the category page is loaded for the first time, pass an empty filter array:

{
  "filters": []
}

The API response returns all available filters with their values and a list of sorting options. This lets you display the full set of filtering tools to the user.

---

Filter value formats in requests

When a user selects filter values, pass them in the corresponding format.

Radio button (radioButtonFilterValue)

Select one value from the list:

{
  "filters": [
    {
      "filterId": "brand",
      "selectedValueIds": ["samsung"]
    }
  ]
}

Checkbox (checkBoxFilterValue)

Select multiple values from the list:

{
  "filters": [
    {
      "filterId": "color",
      "selectedValueIds": ["red", "blue", "green"]
    }
  ]
}

Interval (intervalFilterValue)

Select a range of values:

{
  "filters": [
    {
      "filterId": "price",
      "selectedMin": 5000,
      "selectedMax": 50000
    }
  ]
}

Combined request

You can pass multiple filters at the same time:

{
  "filters": [
    {
      "filterId": "brand",
      "selectedValueIds": ["samsung", "apple"]
    },
    {
      "filterId": "price",
      "selectedMin": 10000,
      "selectedMax": 80000
    },
    {
      "filterId": "color",
      "selectedValueIds": ["black"]
    }
  ]
}

---

Filter formats in responses

The API response returns filters with information about the selected values.

Radio button (radioButtonFilter)

{
  "filterId": "gender",
  "title": "Gender",
  "filterType": "radioButtonFilter",
  "selectedValueId": "male",
  "values": [
    {
      "valueId": "male",
      "valueName": "Male",
      "count": 150
    },
    {
      "valueId": "female",
      "valueName": "Female",
      "count": 200
    }
  ]
}

Checkbox (checkBoxFilter)

{
  "filterId": "brand",
  "title": "Brand",
  "filterType": "checkBoxFilter",
  "values": [
    {
      "valueId": "samsung",
      "valueName": "Samsung",
      "count": 42,
      "isSelected": true
    },
    {
      "valueId": "apple",
      "valueName": "Apple",
      "count": 38,
      "isSelected": false
    }
  ]
}

Interval (intervalFilter)

{
  "filterId": "price",
  "title": "Price",
  "filterType": "intervalFilter",
  "minValue": 1000,
  "maxValue": 150000,
  "selectedMin": 5000,
  "selectedMax": 50000
}

---

Pagination

info

Pagination is supported only for the listing on a category page (POST /category/v2/partners/{partnerId}/products). Pagination is not available for listings on general pages (GET /catalog/v3/...).

Rocket Listing supports two product loading modes.

Infinite scrolling

Use loadSize to specify the number of products in each batch:

?loadSize=20

When loading the next batch, pass contentId from the previous response:

?loadSize=20&contentId=61010bd1-4ed1-4fac-9699-3b8ea39d5f00

Classic pagination

Use the pageSize and page parameters:

?pageSize=20&page=1

To go to the next page:

?pageSize=20&page=2&contentId=61010bd1-4ed1-4fac-9699-3b8ea39d5f00

Important

The contentId parameter fixes the result set and ensures that subsequent results are loaded consistently. Use it only when loading subsequent batches of products; take the value from the previous response.

---

Sending listing interaction data

To support personalization and analytics, send events describing user interactions with the listing.

Tracking interaction events

For more information about the methods, see Recommendation interactions.

---