Display a list of variants
Get multiple variants, either by specifying search criteria/filters or variant IDs.
There are two basic ways to use this endpoint: You can either search for variants by specifying search/filter parameters or directly fetch known variants by their variant IDs.
Searching for variants
The various filter parameters can be used to restrict the list of variants 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 variant 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 variants by variant ID
To fetch a list of known variants, simply specify them by variant ID using the ids parameter, for example, /v1/variants?ids=1,2,3.
If you specify the ids parameter, all other search/filter parameters will be ignored.
Selecting included variant data
By default, only basic variant data is included in the response. Use the with parameters (see below) to include more variant data.
To see all available variant data, for example, for debugging, you might use unrestricted with parameters: ?with=attributes,advancedAttributes.
Beware of using unrestricted with parameters in production applications. It will result in slow performance, as download sizes for full variant 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 variant list optimized for maximum performance is, for example, ?with=attributes:key(ean|shopSize),advancedAttributes:key(modelHeight).
Query parameters
Only include results with variantId matching one of the specified ìds, for example ids=123,456,789.
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
Also include variants with price=0.
Also include sold out results when includeSoldOut is set to true.
Only include results with a productId greater than or equal to minProductId.
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.
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 results with merchantId equal to merchantId. An example would be filters[merchantId]=130.
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).
Only return results with available stock quantity (stock > 0).
Only return results with an available stock quantity greater than or equal to the specified greaterThan quantity.
Include related variant resources, for example, the attributes of a variant can be included using with=attributes or with=attributes:key(plusSize). Multiple includes are separated by commas with=attributes,advancedAttributes.
| with | includes |
|---|---|
| attributes | all attributes |
| attributes:key(<key>,<key>,...) | only attributes with specified keys |
| attributes:type(<type>,<type>,...) | only attributes with specified types |
| advancedAttributes | all advancedAttributes |
| advancedAttributes:key(<key>,<key>,...) | only advancedAttributes with specified keys |
| advancedAttributes:type(<type>,<type>,...) | only advancedAttributes with specified types |
| stock | include stock information (included by default) |
Return results for page (for example, page=2).
Return perPage results per page (for example, perPage=25).
Response
successful operation
Example response
{
"entities": [
{
"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"
}
]
}