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.