Display a list of products
Requesting this API endpoint is the main way to retrieve your product data to display in any context. It will probably be your most used API request.
There are two basic ways to use the endpoint: You can either search for products by specifying search/filter parameters or directly fetch known products by their product IDs.
When you just query /v1/products without any parameter, you will be shown a list of the latest 100 products, sorted by their product ID (highest product ID first).
Searching for products
The various filter parameters can be used to restrict the list of products included in the response (see available parameters below).
You can also use the /v1/filters endpoint to determine which filters are available in the current context. This way, you can, for example, enable users to narrow down general product lists to very specific results by incrementally adding more and more filter parameters.
The minProductId, includeSellableForFree, and includeSoldOut parameters can further restrict or expand the search results (see below).
Fetching products by product ID
To fetch a list of known products, simply specify them by product ID using the ids parameter, for example, /v1/products?ids=1,2,3.
If you specify the ids parameter, all other search/filter parameters will be ignored.
Selecting included product data
By default, only basic product data is included in the response. Use the with parameters (see below) to include more product data.
To see all available product data, for example, for debugging, you might use unrestricted with parameters: ?with=attributes,advancedAttributes,categories,images.attributes,priceRange,reductionRange,siblings,variants.attributes,variants.advancedAttributes.
Beware of using these unrestricted with parameters in production applications. It will result in slow performance, as download sizes for full product data lists can be quite big. Including only exactly what is needed will be best for performance when downloading and parsing the result.
A typical request for a product list optimized for maximum performance is, for example, ?with=attributes:key(brand|color),advancedAttributes:key(description),variants.attributes:key(vendorSize),images,priceRange,reductionRange.
Sorting
You can order the results using different sorting strategies, based on the provided sort, sortingKey, and sortDir parameters.
-
Default sorting: If no sorting parameter is specified, the products will be sorted by product ID. To specify the order, use the sortDir parameter (default desc, highest product ID first).
-
Price sorting: sort=price will sort the results by price. To specify the order, use the sortDir parameter (default desc, highest price first).
-
Reduction sorting: sort=reduction will sort the results by price reduction. This sorting is based on the available appliedReductions for each product's variants. When a campaignKey is also provided, the sorting will also consider the campaign reduction. To specify the order, use the sortDir parameter (default desc, highest reduction first).
-
Date sorting: sort=new will order the products by firstLiveAt field. If firstLiveAt is not set the products will be ordered by creation date. To specify the order, use the sortDir parameter (default desc, most recent date first).
-
Key sorting: sortingKey will order the results based on your custom sorting keys, for example, sortingKey=wcc-default. If the sortingKey parameter has been provided, the sort parameter will be ignored.
Query parameters
Only include results with productId matching one of the specified ids, for example, ids=1,2,3.
Define which attributes should be boosted in the products search result, multiple attributes can be provided separated by , and both the attribute group name or id can be used. e.g: boostAttributes[farbe]=17,7 or boostAttributes[2]=17,7.
Define a float value to boost the attributes used in boostAttributes, it should be a floating point number between 0 and 1.0 e.g: boostAttributes=0.5
Adjust variant price based on the specified campaignKey. If the variant does not have a matching campaign, the default price is returned.
- It will adjust prices also for the price range resource.
- Currently, campaignKey support legacy way campaignKey=px and custom campaigns eg.- campaignKey=4d265817-dd00-4c89-b8e4-c1776e06aa14 which you can find actual keys in campaign API endpoint - /v1/campaigns
Allow performing a contains search using the term specified in the filters[term], it will perform a search analysing a fraction of the content rather than an exact search match.
Attention: When enabled it may affect significantly the search performance, avoid using it for large data sets.
Also include variants with price=0.
Also include sold out results when includeSoldOut is set to true.
Allow fetching products using its reference key
Adjust variant price based on the specified pricePromotionKey. If the variant does not have a matching price promotion, the default price is returned.
Sort results by specified sort type. When no sort is specified, results will be sorted by productId.
| sort | sortDir=asc | sortDir=desc |
|---|---|---|
| price | results with lowest price first | results with highest price first (default) |
| reduction | results with lowest reduction first | results with highest reduction first (default) |
| new | results with oldest creation date first | results with newest creation date first (default) |
| (none) | results with lowest productId first | results with highest productId first (default) |
Sort results in the specified direction (asc for ascending or desc for descending).
Ignore sort parameter and sort results by specified sortingKey instead.
You can only include results with the specified attribute value for the attribute parameter attributeId, e.g., filters[550]=882.
- You can use all attributes available on products as a filter using the parameter with=attributes.
Only include results with the specified attribute value for the attribute parameter attributeKey, e.g,: filters[brand]=882.
- All attributes available on the products via with=attributes might be used as a filter.
Exclude results with the specified attribute value for the attribute parameter attributeKey, e.g,: filters:not[brand]=882&filters:not[color]=549.
- All attributes available on the products via with=attributes might be used as a filter exclusion.
- It can have multiple not filters (e.g. return me all products that are not red and not from Nike) in the query and multiple values for a single attribute(e.g. return me all products that are not red and not green) e.g,: filters:not[color]=545,345
It accepts comma separated attribute filters for OR logic.
- Can be used together with attribute filters
- Example: ?filters[attributeGroup1]=123&filters[attributeGroup2]=456,789&filters[attributeGroup3]=9&orFiltersOperator=attributeGroup2,attributeGroup3 is equivalent of attributeGroup1 AND (attributeGroup2 OR attributeGroup3)
Filter the products which belong to a specific category.
- This filter is configured through the SCAYLE Panel, it is possible to assign a list of products to a given category, based on predetermined criteria defined in the Panel.
Return a list of filters based only on the products matching to a specific ean value, e.g.: filters[ean]=121213213.
You can include only results for products with the specified is_new state.
- The filters[isNew]=true parameter only takes those products into consideration which are considered new.
- The filters[isNew]=false) parameter does not take new products into account.
When is a product considered as new?:
Products are considered "new" when they were inserted into the shop within a period of 28 days. This value can be adjusted accordingly for each shop.
Only include results with a price less than or equal to maxPrice.
Note: The value is passed in a currency's fractional monetary unit (for example, 990 cents for 9,90 EUR).
Only include results with a sale reduction of less than or equal to maxReduction percent. E.g.: filters[maxReduction]=30, for example, will include all products which have 30% or less reduction on the price.
You can include only results with a price greater than or equal to minPrice.
Note: The value is passed in a currency's fractional monetary unit (for example, 990 cents for 9,90 EUR).
Only include results with a sale reduction greater than or equal to minReduction percent. filters[minReduction]=10, for example, will include all products which have at least 10% reduction on the price.
Only include results with the specified product's referenceKey, An example would be filters[referenceKey]=ESR0307001.
You can include only results based on a product's sale state. Products are considered as sale when:
- Any of its variants have a sale price on it.
- There is an activate campaign and the campaignKey=px | <ACTUAL_CAMPAIGN_KEY> is also provided. filters[sale]=true&campaignKey=px | <ACTUAL_CAMPAIGN_KEY>, for example, will include results for both products with sale and campaign prices.
Only include results matching one of the specified styleKeys (also known as masterKeys).
The styleKeys also define the siblings relation between products.
One example would be filters[styleKey]=502227553-1.
Only take into account the result products in which the name or an attribute match a specific searched value, either fully or partially through the term filter, e.g., filters[term]=blue shirts.
Note: The attributes used for searching are configured in the Panel.
Only include products which first appeared live after the provided value.
Note: The provided value shall be datetime in the RFC3339 format: "2020-10-13T00:00:00Z"
Only include products which first appeared live before the provided value.
Note: The provided value shall be datetime in the RFC3339 format: "2020-10-13T00:00:00Z"
Only include results with merchantId equal to merchantId. An example would be filters[merchantId]=130.
You can include only results based on a product's hasCampaignReduction state. Products are considered as hasCampaignReduction when:
- Any of its variants have a prices with hasCampaignReduction on it.
- There is an activate campaign and the campaignKey=px | <ACTUAL_CAMPAIGN_KEY> is also provided. filters[hasCampaignReduction]=true&campaignKey=px | <ACTUAL_CAMPAIGN_KEY>, for example, will include results for both products with hasCampaignReduction and campaign prices.
Include related product resources, for example, the attributes of a product can be included using with=attributes or with=attributes:key(plusSize). Nested includes can be included with with=variants.attributes. Multiple includes are separated by commas with=siblings,variants.
| with | includes |
|---|---|
| attributes | see attributes filtering below |
| advancedAttributes | see attributes filtering below |
| variants | full variants |
| variants.<include> | partial variants (see available includes for variants in /variants endpoint) |
| images | images (included by default) |
| images.attributes | see attributes filtering below |
| categories | categories |
| categories:hidden(true) | also include hidden categories |
| categories.countryLevelCustomData | include country custom data information |
| categories.shopLevelCustomData | include shop custom data information |
| categories.categoryProperties:name(property_name) | only return specified categoryProperties for included categories |
| definingAttributes | definingAttributes |
| siblings | sibling products |
| siblings.<include> | partial sibling products (see available includes for products in /products endpoint) |
| priceRange | priceRange |
| lowestPriorPrice | lowestPriorPrice |
| reductionRange | reductionRange |
| searchCategoryIds | searchCategoryIds |
| baseCategories | baseCategories |
| filters for with=attributes, with=advancedAttributes and with=images.attributes | includes |
|---|---|
| attributes | all attributes |
| attributes:key(<key>|<key>|...) | only attributes with specified keys |
| attributes:type(<type>|<type>|...) | only attributes with specified types |
Only include results with a productId greater than or equal to minProductId.
It allows to ignore the typo tolerance value configured for the search via search configuration, when the parameter is not provided, the typo tolerance is automatically applied according to the configuration.
Return results for page (for example, page=2).
Return perPage results per page (for example, perPage=25).
Return limit results per page (for example, limit=25). Using this parameter is exclusive with both page and perPage and is meant to be used with offset parameter. It will transform the pagination response.
Skips first offset results. Using this parameter is exclusive with both page and perPage and is meant to be used with limit parameter. It will transform the pagination response.
Response
successful operation
Example response
{
"entities": [
{
"baseCategories": [
{
"categoryId": 1866,
"categoryName": "Top",
"categoryPath": "New|Fashion|Frauen|Oberteile|Top"
}
],
"masterKey": "480306626-1",
"firstLiveAt": "2020-09-15T07:34:22+00:00",
"priceRange": {
"max": {
"appliedReductions": [
{
"category": "campaign",
"type": "relative"
}
]
},
"min": {
"appliedReductions": [
{
"category": "campaign",
"type": "relative"
}
]
}
},
"reductionRange": {
"max": {
"appliedReductions": [
{
"category": "campaign",
"type": "relative"
}
]
},
"min": {
"appliedReductions": [
{
"category": "campaign",
"type": "relative"
}
]
}
},
"searchCategoryIds": [
123456,
234567,
345678
],
"variants": [
{
"price": {
"appliedReductions": [
{
"category": "campaign",
"type": "relative"
}
]
},
"productId": 123456,
"referenceKey": "563843898",
"firstLiveAt": "2020-09-15T07:34:22+00:00",
"createdAt": "2023-01-26T09:30:15+00:00",
"updatedAt": "2023-01-26T09:30:15+00:00"
}
],
"createdAt": "2023-01-26T09:30:15+00:00",
"updatedAt": "2023-01-26T09:30:15+00:00",
"indexedAt": "2023-01-26T09:30:15+00:00"
}
]
}