/
Catalog

Catalog

Owned by Thibault Galharret
Last updated: Apr 18, 2025

General display

The catalog displays all the network's products, in the same way as a website. At the top are the different product categories. Below, the products.

By default, the first 25 items in the category are loaded. The next 25 are reloaded when you scroll to the bottom of the page, and so on. To increase the number of items loaded, the pagination_batch_size configuration can be modified.

Path : Configuration > Store App > Pages > Catalog > Specific settings > Options

{ "pagination_batch_size": 50 }

Product search

A search bar at the top of the page allows you to search for articles. The search is based on the fields configured in the config key searchable_fields at the root of the project, that doesn't just affect the Catalog. This configuration can be modified so that the search is based on specific fields. Each table entry is composed of a “name” (the article feature) and a “priority” which ranks the search.

Path : Configuration > Items > Default Item Search Pattern

{ "fields": [ { "name": "name", "priority": 2 }, { "name": "description", "priority": 1 } ] }

The search will return all product references, but by default those with the same product_id will be grouped by color. This configuration can be modified by grouping items according to other features, by modifying the unique_product_filter key.

Path : Configuration > Store App > Pages > Catalog > Specific settings > Options

{ "unique_product_filter": [ "size" ] }

To enhance the experience and avoid unnecessary calls, a 200 millisecond delay is applied after a character is added. This means that a fast typist won't send a request for each character. You can increase or decrease this delay by adjusting the configuration search_input_delay.

Path : Configuration > Store App > Pages > Catalog > Specific settings > Options

{ "search_input_delay": 500 }

Filters

On the side, filters can be configured. By default, they filter on “color” and “size” items features. To modify it, please follow the instructions on this page: Filters

Categories

Categories should be created first, as products are then linked to them. To do this, you need to post them via API on the PUT/categories route. A tree can be built from parent categories and sub-categories.

For each of them, an image and a name must be given in order to display it correctly in the catalog. More information in the API documentation : https://developers.onestock-retail.com/paths/categories/put

Items structure

Once the categories have been created, the article flow must be adapted so that it displays correctly in the store app. To do this, the following fields must be completed:

  • category_ids (mandatory) - path to category or sub-category. Displays the article when the corresponding sub-category is clicked.

  • product_id (optional) - id of the parent, if a product has several variations (size, color, etc.).

  • is_default (optional) - for a product with several variations, indicate which one is the default, so as to display it only once in the catalog.

  • features.{lang}

    • image (mandatory) - product image link, required for display in catalog. To ensure good performance and user experience, we recommend using an image URL with a resolution of 250x250px.

    • name (mandatory) - product name, required for display in catalog.

  • sales_channels_features.{sales_channel}

    • price (mandatory) - effective applied item price in the corresponding sales channel

    • currency (mandatory) - currency in the corresponding sales channel

    • compare_at_price (optional) - crossed-out price, when there is a discount

    • promo_percentage (optional) - discount percentage value

    • disabled (optional) - disappears the item from the catalog in the corresponding sales channel.

For more information on these fields and their formatting, please consult the API documentation https://developers.onestock-retail.com/paths/item_imports-id--items/post. Below is an example of a product flow with all the relevant information.

Query body for POST /items_import/{id}/items

{ "items": { "id": "item_id_01", "product_id": "product_item_id_01", "is_default": true, "category_ids": [ "category_1>subcategory_2" ], "features": { "en": { "image": [ "https://url1.jpg" ], "name": [ "item_name" ] } }, "sales_channels_features": { "sales_channel_1": { "compare_at_price": 10, "currency": "EUR", "disabled": false, "price": 8, "promo_percentage": 20 } } } }

Pricing information

As shown above, pricing information is saved by sales channels. The price, currency, or discount may vary depending on the store's sales channel. For this reason , the id of this sales channel must be stored in the stock location information so that we can display the correct information. If this is not the case, we fallback by default to the sales channel ois. This value can be modified in the configuration key default_sales_channel.

Path : Configuration > Store App > Pages > Catalog > Specific settings > Options

{ "default_sales_channel": "ois_fr" }

If discount information is sent in the “compare_at_price” and “promo_percentage” fields, it is displayed as follows.

We only pass over the value of the price and the percentage discount, no calculations are made at this stage. The information transmitted when the product is created in OneStock must be correct.