v1
latestOpenAPI 3.0.32026-07-173196215.4 KBList products
Requesting this API endpoint is the main way to retrieve your product data to display in any context. A product is basically any individual item in the shop.
There are basically two ways to use this endpoint:
-
Search for products by specifying search/filter parameters
-
Directly fetch known products by their product IDs
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. This offers a notable performance advantage since it eliminates the need for a search step.
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
Retrieve results with productId matching specified ids, for example, ids=1,2,3.
Adjust prices based on the specified campaignKey. If results are not having a matching campaign, the default price is returned.
Please note, that campaign prices are stored in advance and available earlier than the campaign starts.
If includeSellableForFree is set to true, response will also include variants with price=0.
Also include sold out results when includeSoldOut is set to true.
Allow fetching products using its reference key e.g. ?referenceKey=014901100002-Blue.
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 firstLiveAt date first | results with newest firstLiveAt 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.
Only include results with the specified attribute value for the attribute parameter attributeKey, e.g,: filters[brand]=882.
- Any attribute 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.
- Any attribute available on the products via with=attributes might be used as a filter exclusion.
- You can provide multiple not filters (e.g. retrieve all products that are not red and not from brand Nike) in the query and multiple values for a single attribute e.g.: filters:not[color]=545,345
Exclude results with the specified id values e.g. filters:not[id]=100,101.
By default, if multiple filters are given, each filter is working as AND filter. This parameter accepts comma separated attribute group names and enables OR logic for these fields.
- Can be used together with attribute filters
- Example: ?filters[attributeGroup1]=123&filters[attributeGroup2]=456,789&filters[attributeGroup3]=9&orFiltersOperator=attributeGroup2,attributeGroup3 is equivalent to attributeGroup1 AND (attributeGroup2 OR attributeGroup3)
Filter the products which belong to a specific category.
Retrieve a list of products matching the specified 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 retrieves products which are considered new.
- The filters[isNew]=false parameter only retrieves products which are not considered new.
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 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.
Only include 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 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. Multiple referenceKeys can be given with a comma as a separator.
Only retrieve products with the specified variant's referenceKey. Multiple referenceKeys can be given with a comma as a separator.
Only retrieve products that have a variant which matches the provided attribute parameters.
Only include results based on a products' sale state. Products are considered as sale when:
- Any of its variants is on sale.
- There is an active campaign and the campaignKey={campaignKey} is given.
Only include results that are matching given masterKeys (also known as styleKeys). The masterKey define the siblings relation between products.
Multiple masterKeys can be given with a comma as a separator.
Term-based search that returns products where the provided search term matches the name or attribute value within the products. E.g., filters[term]=blue shirts
Note: The attributes used for searching are configured in the Panel.
The API will split the searched term into multiple words. Then it will try to match each of these words against products' name and searchable attributes. The better the searched term matches against a product, the higher the product is returned. But it only requires a single word to match for a product to be returned.
A detailed explanation of the functionality can be found in SCAYLE Panel developer guide
Retrieve 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 results with merchantId equal to the given merchantId. Example: filters[merchantId]=130.
Only include results that have a campaign reduction for the given campaignKey. This filter can only be used together with an active campaign key and will return results that have a campaign reductions in the campaign.
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 disables the typo tolerance value configured for this request. When the parameter is not provided, the typo tolerance is automatically applied according to the typo tolerance configuration in SCAYLE panel.
Return results for page (for example, page=2).
Return perPage number of 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