Search endpoint

/v2/shop/search

Attribute Filters

Attributes allow filtering based on product characteristics (e.g., Color, Size, Material). To apply a filter, use the parameter attributes followed by the attribute name and value, separated by a pipe symbol (|).

Syntax

GET /v2/shop/search?locale=xx-XX&currency=XXX&attributes=AttributeName%7CAttributeValue

💡

Example

GET /v2/shop/search?locale=fr-FR&currency=EUR&attributes=Color%7CBlue

Result: Returns all products or variants where the attribute Color equals Blue.

Multiple Attributes

To filter using several different attributes, repeat the attributes parameter for each condition. Results will include products that meet all selected attribute conditions (AND logic).

GET /v2/shop/search?locale=xx-XX&currency=XXX&attributes=AttributeName%7CAttributeValue&attributes=AttributeName%7CAttributeValue

💡

Example

GET /v2/shop/search?locale=fr-FR&currency=EUR&attributes=Color%7CBlue&attributes=Size%7CMedium

Result: Returns products that are Blue and Medium.

Multiple Values for the Same Attribute

To filter by several values of the same attribute, repeat the attributes parameter with the same attribute name but different values. Results will include products that match any of the selected values (OR logic).

GET /v2/shop/search?locale=xx-XX&currency=XXX&attributes=AttributeName%7CAttributeValue&attributes=AttributeName%7CAttributeValue

💡

Example

GET /v2/shop/search?locale=fr-FR&currency=EUR&attributes=Color%7CBlue&attributes=Color%7CRed

Result: Returns products that are Blue, Red, or both.

Attribute Data in the Response

Attributes are available in both the facet object and product object of the response.

"facets": {
  "attributes": [
    {
      "ID": "123",
      "Name": "Color",
      "Values": ["Red", "Blue"]
    }
  ]
},
"product": {
  "attributes": [
    {
      "ID": "123",
      "Name": "Color",
      "Values": ["Red"]
    }
  ]
}

Custom Field Filters

Custom fields are user-defined data points used for business-specific filtering (e.g., Promo, DeliveryType). They behave exactly like attributes and follow the same OR/AND logic.

Syntax

GET /v2/shop/search?locale=xx-XX&currency=XXX&customFields=CustomFieldName%7CCustomFieldValue

💡

Example

GET /v2/shop/search?locale=fr-FR&currency=EUR&customFields=Promo%7Cyes

Result: Returns all products where the custom field Promo equals yes.

Multiple Custom Fields

You can filter by several custom fields by repeating the customFields parameter.

💡

Example

GET /v2/shop/search?locale=fr-FR&currency=EUR&customFields=Promo%7Cyes&customFields=DeliveryType%7CParcel

Result: Returns products where Promo = yes and DeliveryType = Parcel.

Multiple Values for the Same Custom Field

When multiple values of the same custom field are passed, the logic is OR.

💡

Example

GET /v2/shop/search?locale=fr-FR&currency=EUR&customFields=DeliveryType%7CPallet&customFields=DeliveryType%7CParcel

Result: Returns all products where DeliveryType is Pallet, Parcel, or both.

Custom Field Data in the Response

"facets": {
  "customFields": [
    {
      "ID": "456",
      "Name": "Promo",
      "Values": ["Yes", "No"]
    }
  ]
},
"product": {
  "customFields": [
    {
      "ID": "456",
      "Name": "Promo",
      "Values": ["Yes"]
    }
  ]
}

Brand Filter

To filter by product brand, use the parameter brand with the brand name as the value.

GET /v2/shop/search?locale=xx-XX&brand=BrandName

💡

Example

GET /v2/shop/search?locale=fr-FR&brand=Opo

Result: Returns all products associated with the brand Opo.

Product Tags Filter

To filter by product tags, use the parameter productTag with the business ID of the tag.

GET /v2/shop/search?locale=xx-XX&productTag=TagBusinessID

💡

Example

GET /v2/shop/search?locale=fr-FR&productTag=000025

Result: Returns all products associated with the tag whose business ID is 000025.

Navigation Categories as Facets

Navigation Categories are supported as dynamic facets in the product search API. This allows users to filter products based on predefined navigation entries, just like other attributes or brand filters.

General behavior

• Navigations are now returned under the facets.navigations block of the search response.
• Navigation facets are always enabled. No configuration is required.
• Navigation Categories are only available as facets if they have been indexed.

Facet filtering logic

Facet filtering logic

API

The facets API does not expose the full navigation tree (no parent-child relationship).

To build a hierarchy in the UI:

1. Call GET /v1/shop/navigation-category/online to return the full navigation tree structure
2. Identify leaf categories (nodes with no children)
3. Call /v2/shop/search to return the list of navigations available in the search response
4. Display only Navigations' leaves that are also present in the search response

"facets": {
  "navigations": [
    { "id": "N1", "name": "Hand tools" },
    { "id": "N2", "name": "Electric saws" }
  ]
}

5. When the user selects a navigation leaf, include its ID in the search query (e.g., /v2/shop/search?categoryIds=N1).

sequenceDiagram
  participant Frontend
  participant API

  Frontend->>API: 1. GET /v1/shop/navigation-category/online
  API-->>Frontend: Returns full navigation tree
  
Frontend->>Frontend: 2. Identify leaf nodes

  Frontend->>API: 3. GET /v2/shop/search
  API-->>Frontend: Returns facets.navigations

Frontend->>Frontend: 4. Cross-check with local tree and display only relevant leaves

Frontend->>Frontend : Filter on Navigation "N1"

 Frontend->>API: 5. GET /v2/shop/search?categoryIds=N1
 API-->>Frontend: Return the products linked to the Navigation Category N1

⚠️

Sync between Navigation tree and Search results

If the indexation has not been run yet or is outdated, the navigation categories visible via /navigation-category/online may not appear in the Search API response.

• The endpoint GET /v1/shop/navigation-category/online returns the full navigation tree, including all categories, even those not currently linked to indexed products.
• However, the GET /v2/shop/search API only includes navigation categories that are indexed.

Best practices

• Build the tree structure locally using the /navigation-category/online endpoint.
• Avoid displaying empty navigation filters. If a leaf is not returned, it means no products are assigned to it.
• Navigation facets are always enabled. There is no back office config needed.
• Make sure a successful and up-to-date product indexation has been completed.