Using Products in your Store
General
Learn how to use products in your store.
Storefront API
Get single product
Fetch a single product using its ID.
Use this method when you want to query a single product with more detailed information. For example, this method can be useful for querying a product on the product detail page.
You can request more detailed information via the optional with parameter.
For querying multiple products at the same time, see Get Multiple Products.
Parameters
| Parameter | Details |
|---|---|
| productId | Integer ID of the product. |
| with | Object Used to request the optional fields. Possible keys: |
| campaignKey | String Use to get the correct prices for the specified campaign. |
For the complete list of supported parameters refer to our Storefront API Reference Guide.
Examples
All examples require a configured Storefront API client being available as client.
See Authentication for how to set up.
Get Product with specific attributes
Let's say we want to create a product detail page to show information about a t-shirt product with id 1. We would use the getById method. Besides basic fields we need to tell the API which attributes we would like to receive. Usually on a product detail page we want to receive the name, description, images, prices, colors and sizes. We get the product with these attributes as follows:
// Get product with id 1 and its attributes
const product = await client.products.getById(1, {
with: {
attributes: {
withKey: ["name", "description", "color"],
},
images: "all",
variants: {
attributes: {
withKey: ["size"],
},
},
},
});
console.log(product.attributes.name.values.label);
// => Hilfiger Shirt
Response
{
"id": 1,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:05:34+00:00",
"indexedAt": "2023-09-12T18:43:39+00:00",
"firstLiveAt": "2023-06-12T14:05:33+00:00",
"masterKey": "THS090600",
"referenceKey": "THS0906008000001",
"attributes": {
"color": {
"id": 1001,
"key": "color",
"label": "Color",
"type": "",
"multiSelect": false,
"values": { "id": 9, "label": "Darkblue", "value": "darkblue" }
},
"name": {
"id": 20005,
"key": "name",
"label": "Name",
"type": "",
"multiSelect": false,
"values": { "id": 20005, "label": "Hilfiger Shirt", "value": "name" }
},
"description": {
"id": 20006,
"key": "description",
"label": "Description",
"type": "",
"multiSelect": false,
"values": { "id": 20006, "label": "", "value": "description" }
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/cd81a5d37e4241686586812d9e179553?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/1c98f7fc408b9d2cca91abfbf5650df1?bg=F4F4F5&quality=75&height=1067&width=800, https://cdn.aboutstatic.com/f",
"attributes": {}
}
],
"variants": [
{
"id": 1,
"referenceKey": "THS0906008000001_S",
"attributes": {
"size": {
"id": 1002,
"key": "size",
"label": "Size",
"type": "",
"multiSelect": false,
"values": { "id": 28, "label": "S", "value": "s" }
}
},
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-08-28T11:19:33+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 31,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": { "deliveryEstimate": [] }
},
{
"id": 2,
"referenceKey": "THS0906008000001_M",
"attributes": {
"size": {
"id": 1002,
"key": "size",
"label": "Size",
"type": "",
"multiSelect": false,
"values": { "id": 29, "label": "M", "value": "m" }
}
},
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-08-28T11:19:33+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
},
{
"id": 3,
"referenceKey": "THS0906008000001_L",
"attributes": {
"size": {
"id": 1002,
"key": "size",
"label": "Size",
"type": "",
"multiSelect": false,
"values": { "id": 30, "label": "L", "value": "l" }
}
},
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
}
],
"customData": {}
}
Get Product with all Attributes
For our product detail page we want to show all related product attributes, not just the name. We can retrieve all attributes as follows:
// Get product with id 1 and all attributes
const product = await client.products.getById(1, {
with: {
attributes: "all",
},
});
console.log(product.attributes.sleevelength.values.label);
// => quarterarm
Response
{
"id": 1,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:05:34+00:00",
"indexedAt": "2023-06-19T16:09:59+00:00",
"firstLiveAt": "2023-06-12T14:05:33+00:00",
"masterKey": "THS090600",
"referenceKey": "THS0906008000001",
"attributes": {
"length": {
"id": 1007,
"key": "length",
"label": "Length",
"type": "",
"multiSelect": true,
"values": ["Array"]
},
"elasticity": {
"id": 1010,
"key": "elasticity",
"label": "Elasticity",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"category": {
"id": 551,
"key": "category",
"label": "Master Categories (AG)",
"type": "",
"multiSelect": true,
"values": ["Array"]
},
"brand": {
"id": 550,
"key": "brand",
"label": "Brand",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"producttype": {
"id": 1004,
"key": "producttype",
"label": "Producttype",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"badges": {
"id": 1011,
"key": "badges",
"label": "Badges",
"type": "",
"multiSelect": true,
"values": ["Array"]
},
"overallLength": {
"id": 1009,
"key": "overallLength",
"label": "Overalllength",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"designExtras": {
"id": 1005,
"key": "designExtras",
"label": "Design & Extras",
"type": "",
"multiSelect": true,
"values": ["Array"]
},
"brandLogo": {
"id": 20000,
"key": "brandLogo",
"label": "Brand logo",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"sleevelength": {
"id": 1006,
"key": "sleevelength",
"label": "Sleevelength",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"fit": {
"id": 1008,
"key": "fit",
"label": "Fit",
"type": "",
"multiSelect": true,
"values": ["Array"]
},
"countrypermission": {
"id": 1013,
"key": "countrypermission",
"label": "Countrtpermission",
"type": "",
"multiSelect": true,
"values": ["Array"]
},
"name": {
"id": 20005,
"key": "name",
"label": "Name",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"color": {
"id": 1001,
"key": "color",
"label": "Color",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"material": {
"id": 1003,
"key": "material",
"label": "Material",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"description": {
"id": 20006,
"key": "description",
"label": "Description",
"type": "",
"multiSelect": false,
"values": ["Object"]
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/cd81a5d37e4241686586812d9e179553?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/1c98f7fc408b9d2cca91abfbf5650df1?bg=F4F4F5&quality=75&height=1067&width=800, https://cdn.aboutstatic.com/f",
"attributes": {}
}
],
"customData": {}
}
Get Product with Variants
For our product detail page we want to show all related product attributes, not just the name. We can retrieve all attributes as follows:
// Get product with id 1, all attributes and size variants
const product = await adminApi.products.getById(1, {
with: {
attributes: "all",
variants: {
attributes: "all",
},
},
});
const variants = product.variants.map(
(variant) => variant.attributes.size.values.label
);
console.log(variants);
// => [ 'S', 'M', 'L' ]
Response
{
"id": 1,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:05:34+00:00",
"indexedAt": "2023-06-19T17:09:59+00:00",
"firstLiveAt": "2023-06-12T14:05:33+00:00",
"masterKey": "THS090600",
"referenceKey": "THS0906008000001",
"attributes": {
"badges": {
"id": 1011,
"key": "badges",
"label": "Badges",
"type": "",
"multiSelect": true,
"values": ["Array"]
},
"designExtras": {
"id": 1005,
"key": "designExtras",
"label": "Design & Extras",
"type": "",
"multiSelect": true,
"values": ["Array"]
},
"description": {
"id": 20006,
"key": "description",
"label": "Description",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"countrypermission": {
"id": 1013,
"key": "countrypermission",
"label": "Country Permission",
"type": "",
"multiSelect": true,
"values": ["Array"]
},
"brand": {
"id": 550,
"key": "brand",
"label": "Brand",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"color": {
"id": 1001,
"key": "color",
"label": "Color",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"elasticity": {
"id": 1010,
"key": "elasticity",
"label": "Elasticity",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"material": {
"id": 1003,
"key": "material",
"label": "Material",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"sleevelength": {
"id": 1006,
"key": "sleevelength",
"label": "Sleeve Length",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"length": {
"id": 1007,
"key": "length",
"label": "Length",
"type": "",
"multiSelect": true,
"values": ["Array"]
},
"fit": {
"id": 1008,
"key": "fit",
"label": "Fit",
"type": "",
"multiSelect": true,
"values": ["Array"]
},
"producttype": {
"id": 1004,
"key": "producttype",
"label": "Product Type",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"brandLogo": {
"id": 20000,
"key": "brandLogo",
"label": "Brand logo",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"category": {
"id": 551,
"key": "category",
"label": "Master Categories (AG)",
"type": "",
"multiSelect": true,
"values": ["Array"]
},
"name": {
"id": 20005,
"key": "name",
"label": "Name",
"type": "",
"multiSelect": false,
"values": ["Object"]
},
"overallLength": {
"id": 1009,
"key": "overallLength",
"label": "Overall Length",
"type": "",
"multiSelect": false,
"values": ["Object"]
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/cd81a5d37e4241686586812d9e179553?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/1c98f7fc408b9d2cca91abfbf5650df1?bg=F4F4F5&quality=75&height=1067&width=800, https://cdn.aboutstatic.com/f",
"attributes": {}
}
],
"variants": [
{
"id": 1,
"referenceKey": "THS0906008000001_S",
"attributes": ["Object"],
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:06:21+00:00",
"stock": ["Object"],
"price": ["Object"],
"customData": {}
},
{
"id": 2,
"referenceKey": "THS0906008000001_M",
"attributes": ["Object"],
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:06:21+00:00",
"stock": ["Object"],
"price": ["Object"],
"customData": {}
},
{
"id": 3,
"referenceKey": "THS0906008000001_L",
"attributes": ["Object"],
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": ["Object"],
"price": ["Object"],
"customData": {}
}
],
"customData": {}
}
Sorting product's variants based on sizes
The desired order on a product detail page is to have sizes displayed in the correct order as S, M, L, XL, and XXL. However, when we receive a response from the Storefront API, the sizes appear in a different order: L, XL, XXL, S, M. This discrepancy in order is due to the timing of when these variants were created. For instance, if variant S was created after variant XXL, it will be displayed after it.
To address this issue, a practical solution is to establish an additional attribute group, such as "variant sorting," and create an automated attribute group mapping between your size attribute group and your sorting attribute group. In this setup, you can map size S to 1, M to 2, L to 3, and so forth. Consequently, as soon as a variant is assigned a size, it will automatically be assigned a sorting number. This sorting number can then be utilized on the Storefront to display the sizes in the desired order on your frontend.
In the following example, we'll demonstrate how to configure the attribute groups using the SCAYLE Panel. These steps can also be accomplished using the Admin API.
Create AttributeGroup
- In the SCAYLE Panel go to
Settings > Products Structure > Attributes - Click + Add Attribute Group.
- Set a name and frontend name, e.g.
variantSorting. - Set Entity level to variant.
- Check the box for Relevant for mapping
- Click Save.
.png)
Set Sorting Attributes
- Go to the just created attribute group
variantSorting - Under attributes add five attributes with values from 1 to 5.
.png)
Map Sizes to variantSorting
- Go to attribute group
GrößeorSizesand select Mapping - Click New Mapping and select
variantSorting - Now select and save for each size the number in order, e.g. S=1, M=2, L=3…
.png)
Now in we can add variantSorting as attribute in our product query and use the new attribute for sorting in our frontend.
// Get product with id 1, all attributes and size variants
const product = await adminApi.products.getById(1, {
with: {
attributes: "all",
variants: {
attributes: "all",
},
},
});
// Sort variants by our new variantSorting attribute
const sortedVariants = product.variants.sort((a, b) => {
return (
a.attributes.variantSorting.values.value -
b.attributes.variantSorting.values.value
);
});
const sizes = sortedVariants.map(
(variant) => variant.attributes.size.values.label
);
console.log(sizes);
// => [ 'S', 'M', 'L' ]
Response
{
"id": 1,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-10-23T13:25:05+00:00",
"indexedAt": "2023-10-23T13:46:43+00:00",
"firstLiveAt": "2023-06-12T14:05:33+00:00",
"masterKey": "THS090600",
"referenceKey": "THS0906008000001",
"attributes": {
"fit": {
"id": 1008,
"key": "fit",
"label": "Fit",
"type": "",
"multiSelect": true,
"values": [
{ "id": 25, "label": "Slim Fit", "value": "slim_fit" }
]
},
"countrypermission": {
"id": 1013,
"key": "countrypermission",
"label": "Country Permission",
"type": "",
"multiSelect": true,
"values": [
{ "id": 37, "label": "Germany", "value": "germany" },
{ "id": 38, "label": "England", "value": "england" },
{ "id": 39, "label": "Spain", "value": "spain" }
]
},
"brandLogo": {
"id": 20000,
"key": "brandLogo",
"label": "Brand logo",
"type": "",
"multiSelect": false,
"values": { "id": 10, "label": "Tommy Hilfiger", "value": "" }
},
"brand": {
"id": 550,
"key": "brand",
"label": "Brand",
"type": "",
"multiSelect": false,
"values": {
"id": 10,
"label": "Tommy Hilfiger",
"value": "tommy_hilfiger"
}
},
"producttype": {
"id": 1004,
"key": "producttype",
"label": "Product Type",
"type": "",
"multiSelect": false,
"values": { "id": 12, "label": "Shirt", "value": "shirt" }
},
"color": {
"id": 1001,
"key": "color",
"label": "Color",
"type": "",
"multiSelect": false,
"values": { "id": 9, "label": "Dark blue", "value": "darkblue" }
},
"sleevelength": {
"id": 1006,
"key": "sleevelength",
"label": "Sleeve Length",
"type": "",
"multiSelect": false,
"values": { "id": 31, "label": "Short sleeves", "value": "shortsleeves" }
},
"category": {
"id": 551,
"key": "category",
"label": "Master Categories (AG)",
"type": "",
"multiSelect": true,
"values": [
{ "id": 5, "label": "Men", "value": "5" },
{ "id": 6, "label": "Men|Clothing", "value": "6" },
{ "id": 7, "label": "Men|Clothing|Shirts", "value": "7" }
]
},
"elasticity": {
"id": 1010,
"key": "elasticity",
"label": "Elasticity",
"type": "",
"multiSelect": false,
"values": {
"id": 27,
"label": "Elastic/strech",
"value": "elasticstretch"
}
},
"badges": {
"id": 1011,
"key": "badges",
"label": "Badges",
"type": "",
"multiSelect": true,
"values": [
{
"id": 32,
"label": "Do Not Tumble Dry",
"value": "do_not_tumble_dry"
},
{
"id": 33,
"label": "Do Not Iron",
"value": "do_not_iron"
},
{ "id": 34, "label": "30°C Delicates", "value": "30c_delicates" },
{
"id": 35,
"label": "Dry Clean with Perchloroethylene",
"value": "dry_clean_with_perschlorothylene"
},
{ "id": 36, "label": "Do Not Bleach", "value": "do_not_bleach" }
]
},
"material": {
"id": 1003,
"key": "material",
"label": "Material",
"type": "",
"multiSelect": false,
"values": { "id": 11, "label": "Cotton", "value": "cotton" }
},
"name": {
"id": 20005,
"key": "name",
"label": "Name",
"type": "",
"multiSelect": false,
"values": { "id": 20005, "label": "Hilfiger Shirt", "value": "name" }
},
"length": {
"id": 1007,
"key": "length",
"label": "Length",
"type": "",
"multiSelect": true,
"values": [
{ "id": 24, "label": "Normal Length", "value": "normal_length" }
]
},
"overallLength": {
"id": 1009,
"key": "overallLength",
"label": "Overall Length",
"type": "",
"multiSelect": false,
"values": { "id": 26, "label": "70 cm", "value": "70_cm" }
},
"description": {
"id": 20006,
"key": "description",
"label": "Description",
"type": "",
"multiSelect": false,
"values": { "id": 20006, "label": "", "value": "description" }
},
"designExtras": {
"id": 1005,
"key": "designExtras",
"label": "Design & Extras",
"type": "",
"multiSelect": true,
"values": [
{ "id": 13, "label": "Melange", "value": "melange" },
{ "id": 14, "label": "Jersey", "value": "jersey" },
{
"id": 15,
"label": "Round Neckline",
"value": "roundneckline"
},
{
"id": 16,
"label": "Stitched hem/edge",
"value": "stitched_hemedge""
},
{ "id": 17, "label": "Straight Hem", "value": "staright_hem" },
{ "id": 18, "label": "Straight Cut", "value": "straight_cut" },
{ "id": 19, "label": "Necktape", "value": "necktape" },
{
"id": 20,
"label": "Flammgarn-Struktur",
"value": "flammgarnstruktur"
},
{ "id": 21, "label": "Label Embroidery", "value": "label_embroidery" },
{ "id": 22, "label": "Ton-on-Ton-Seams", "value": "tonontonseams" },
{ "id": 23, "label": "Soft Grip", "value": "soft_grip" }
]
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/cd81a5d37e4241686586812d9e179553?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/1c98f7fc408b9d2cca91abfbf5650df1?bg=F4F4F5&quality=75&height=1067&width=800, https://cdn.aboutstatic.com/f",
"attributes": {}
}
],
"variants": [
{
"id": 1,
"referenceKey": "THS0906008000001_S",
"attributes": {
"size": {
"id": 1002,
"key": "size",
"label": "Size",
"type": "",
"multiSelect": false,
"values": { "id": 30, "label": "S", "value": "s" }
},
"variantSorting": {
"id": 1021,
"key": "variantSorting",
"label": "variantSorting",
"type": "",
"multiSelect": false,
"values": { "id": 106, "label": "1", "value": "1" }
}
},
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-08-28T11:19:33+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 31,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": { "deliveryEstimate": [] }
},
{
"id": 2,
"referenceKey": "THS0906008000001_M",
"attributes": {
"size": {
"id": 1002,
"key": "size",
"label": "Size",
"type": "",
"multiSelect": false,
"values": { "id": 29, "label": "M", "value": "m" }
},
"variantSorting": {
"id": 1021,
"key": "variantSorting",
"label": "variantSorting",
"type": "",
"multiSelect": false,
"values": { "id": 105, "label": "2", "value": "2" }
}
},
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-08-28T11:19:33+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
},
{
"id": 3,
"referenceKey": "THS0906008000001_L",
"attributes": {
"size": {
"id": 1002,
"key": "size",
"label": "Größe",
"type": "",
"multiSelect": false,
"values": { "id": 30, "label": "L", "value": "l" }
},
"variantSorting": {
"id": 1021,
"key": "variantSorting",
"label": "variantSorting",
"type": "",
"multiSelect": false,
"values": { "id": 104, "label": "3", "value": "3" }
}
},
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
}
],
"customData": {}
}
Get Reduced Campaign Prices
Sometimes we have an active price campaign running. When we pass its campaignKey we get adjusted prices based on the campaigns reduction:
const response = await adminApi.products.getById(1, {
with: {
attributes: "all",
variants: {
attributes: "all",
},
},
campaignKey: "promo_test_20", // here we pass the campaign key
});
const price = response.variants[0].price;
const savings = price.appliedReductions[0].amount.absoluteWithTax;
const oldPrice = savings + price.withTax;
console.log(`Price: ${price.withTax}`);
console.log(`Savings: ${savings}`);
console.log(`Previous Price: ${oldPrice}`);
// Price: 3192
// Savings: 798
// Previous Price: 3990
Response
{
"id": 1,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:05:34+00:00",
"indexedAt": "2023-09-29T10:46:13+00:00",
"firstLiveAt": "2023-06-12T14:05:33+00:00",
"masterKey": "THS090600",
"referenceKey": "THS0906008000001",
"attributes": {
"length": {
"id": 1007,
"key": "length",
"label": "Length",
"type": "",
"multiSelect": true,
"values": [
{ "id": 24, "label": "Normal Length", "value": "normal_length" }
]
},
"countrypermission": {
"id": 1013,
"key": "countrypermission",
"label": "Country Permission",
"type": "",
"multiSelect": true,
"values": [
{ "id": 37, "label": "Germany", "value": "germany" },
{ "id": 38, "label": "England", "value": "england" },
{ "id": 39, "label": "Spain", "value": "spain" }
]
},
"description": {
"id": 20006,
"key": "description",
"label": "Description",
"type": "",
"multiSelect": false,
"values": { "id": 20006, "label": "", "value": "description" }
},
"sleevelength": {
"id": 1006,
"key": "sleevelength",
"label": "Ärmellänge",
"type": "",
"multiSelect": false,
"values": { "id": 31, "label": "Short sleeves", "value": "shortsleeves" }
},
"color": {
"id": 1001,
"key": "color",
"label": "Farbe",
"type": "",
"multiSelect": false,
"values": { "id": 9, "label": "Darkblue", "value": "darkblue" }
},
"brandLogo": {
"id": 20000,
"key": "brandLogo",
"label": "Brand logo",
"type": "",
"multiSelect": false,
"values": { "id": 10, "label": "Tommy Hilfiger", "value": "" }
},
"overallLength": {
"id": 1009,
"key": "overallLength",
"label": "Overall Length",
"type": "",
"multiSelect": false,
"values": { "id": 26, "label": "70 cm", "value": "70_cm" }
},
"brand": {
"id": 550,
"key": "brand",
"label": "Brand",
"type": "",
"multiSelect": false,
"values": {
"id": 10,
"label": "Tommy Hilfiger",
"value": "tommy_hilfiger"
}
},
"producttype": {
"id": 1004,
"key": "producttype",
"label": "Produkt Type",
"type": "",
"multiSelect": false,
"values": { "id": 12, "label": "Shirt", "value": "shirt" }
},
"designExtras": {
"id": 1005,
"key": "designExtras",
"label": "Design & Extras",
"type": "",
"multiSelect": true,
"values": [
{ "id": 13, "label": "Melange", "value": "melange" },
{ "id": 14, "label": "Jersey", "value": "jersey" },
{
"id": 15,
"label": "Round-Neckline",
"value": "roundneckline"
},
{
"id": 16,
"label": "Stitched Hem/Edge",
"value": "stitched_hemedge"
},
{ "id": 17, "label": "Straight Hem", "value": "straight_hem" },
{ "id": 18, "label": "Straight Cut", "value": "straight_cut" },
{ "id": 19, "label": "Necktape", "value": "necktape" },
{ "id": 21, "label": "Label Embroidery", "value": "label_embroidery" },
{ "id": 22, "label": "Ton-on-Ton-Seams", "value": "tonontonseams" },
{ "id": 23, "label": "Soft Grip", "value": "soft_grip" }
]
},
"fit": {
"id": 1008,
"key": "fit",
"label": "Fit",
"type": "",
"multiSelect": true,
"values": [
{ "id": 25, "label": "Slim fit", "value": "slim_fit" }
]
},
"badges": {
"id": 1011,
"key": "badges",
"label": "Badges",
"type": "",
"multiSelect": true,
"values": [
{
"id": 32,
"label": "Do Not Tumble Dry",
"value": "do_not_tumble_dry"
},
{
"id": 33,
"label": "Do Not Iron",
"value": "do_not_iron"
},
{ "id": 34, "label": "30°C Delicates", "value": "30c_delicates" },
{
"id": 35,
"label": "Dry Clean with Perchloroethylene",
"value": "dryclean_with_perchloroethylene"
},
{ "id": 36, "label": "Do Not Bleach", "value": "do_not_bleach" }
]
},
"material": {
"id": 1003,
"key": "material",
"label": "Material",
"type": "",
"multiSelect": false,
"values": { "id": 11, "label": "Cotton", "value": "cotton" }
},
"elasticity": {
"id": 1010,
"key": "elasticity",
"label": "Elasticity",
"type": "",
"multiSelect": false,
"values": {
"id": 27,
"label": "Elastic/Stretch",
"value": "elasticstretch"
}
},
"category": {
"id": 551,
"key": "category",
"label": "Master Categories (AG)",
"type": "",
"multiSelect": true,
"values": [
{ "id": 5, "label": "Men", "value": "5" },
{ "id": 6, "label": "Men|Clothing", "value": "6" },
{ "id": 7, "label": "Men|Clothing|Shirts", "value": "7" }
]
},
"name": {
"id": 20005,
"key": "name",
"label": "Name",
"type": "",
"multiSelect": false,
"values": { "id": 20005, "label": "Hilfiger Shirt", "value": "name" }
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/cd81a5d37e4241686586812d9e179553?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/1c98f7fc408b9d2cca91abfbf5650df1?bg=F4F4F5&quality=75&height=1067&width=800, https://cdn.aboutstatic.com/f",
"attributes": {}
}
],
"variants": [
{
"id": 1,
"referenceKey": "THS0906008000001_S",
"attributes": {
"size": {
"id": 1002,
"key": "size",
"label": "Size",
"type": "",
"multiSelect": false,
"values": { "id": 28, "label": "S", "value": "s" }
}
},
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-08-28T11:19:33+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 31,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3192,
"withoutTax": 2682,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 510, "rate": 0.19 } },
"appliedReductions": [
{
"category": "campaign",
"type": "relative",
"amount": { "relative": 0.2, "absoluteWithTax": 798 }
}
]
},
"customData": { "deliveryEstimate": [] }
},
{
"id": 2,
"referenceKey": "THS0906008000001_M",
"attributes": {
"size": {
"id": 1002,
"key": "size",
"label": "Size",
"type": "",
"multiSelect": false,
"values": { "id": 29, "label": "M", "value": "m" }
}
},
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-08-28T11:19:33+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3192,
"withoutTax": 2682,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 510, "rate": 0.19 } },
"appliedReductions": [
{
"category": "campaign",
"type": "relative",
"amount": { "relative": 0.2, "absoluteWithTax": 798 }
}
]
},
"customData": {}
},
{
"id": 3,
"referenceKey": "THS0906008000001_L",
"attributes": {
"size": {
"id": 1002,
"key": "size",
"label": "Size",
"type": "",
"multiSelect": false,
"values": { "id": 30, "label": "L", "value": "l" }
}
},
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3192,
"withoutTax": 2682,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 510, "rate": 0.19 } },
"appliedReductions": [
{
"category": "campaign",
"type": "relative",
"amount": { "relative": 0.2, "absoluteWithTax": 798 }
}
]
},
"customData": {}
}
],
"customData": {}
}
Get Product with applied Promotion key
Another way to get special prices, e.g. due to a promotion or overwritten merchant prices, is to provide the related pricePromotionKey.
For this example we first need to create such a promotion in the panel. We can do that by importing merchant prices:
- Download
demoPrices.csv - In the SCAYLE Panel go to Settings
- In the sidebar open Imports & Jobs -> Imports
- Click +New Import
- In the now opened modal select Overwrite Merchant Prices
- Click Choose File and select the downloaded CSV file
- Click Validate and Confirm
- Proceed to Scheduling and submit to a user to review
- After reviewer confirmation the prices are imported and we see price changes
It can take up to one hour until the products with new prices are indexed again.
const response = await adminApi.products.getById(1, {
with: {
variants: "all",
},
pricePromotionKey: "test", // here we pass the price promotion key
});
const price = response.variants[0].price;
const savings = price.appliedReductions[0].amount.absoluteWithTax;
const oldPrice = savings + price.withTax;
console.log(`Price: ${price.withTax}`);
console.log(`Savings: ${savings}`);
console.log(`Previous Price: ${oldPrice}`);
// Price: 1500
// Savings: 2490
// Previous Price: 3990
Response
{
"id": 1,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-10-23T14:41:56+00:00",
"indexedAt": "2023-10-31T08:20:42+00:00",
"firstLiveAt": "2023-06-12T14:05:33+00:00",
"masterKey": "THS090600",
"referenceKey": "THS0906008000001",
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/cd81a5d37e4241686586812d9e179553?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/1c98f7fc408b9d2cca91abfbf5650df1?bg=F4F4F5&quality=75&height=1067&width=800, https://cdn.aboutstatic.com/f",
"attributes": {}
}
],
"variants": [
{
"id": 1,
"referenceKey": "THS0906008000001_S",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-08-28T11:19:33+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 31,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 1500,
"withoutTax": 1261,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 239, "rate": 0.19 } },
"appliedReductions": [
{
"category": "sale",
"type": "relative",
"amount": { "relative": 0.62, "absoluteWithTax": 2490 }
}
]
},
"appliedPricePromotionKey": "test",
"customData": { "deliveryEstimate": [] }
},
{
"id": 2,
"referenceKey": "THS0906008000001_M",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-08-28T11:19:33+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 4500,
"withoutTax": 3782,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 718, "rate": 0.19 } },
"appliedReductions": []
},
"appliedPricePromotionKey": "test",
"customData": {}
},
{
"id": 3,
"referenceKey": "THS0906008000001_L",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
}
],
"customData": {}
}
Get multiple products
Retrieve all products in a given category by iterating through their result pages.
The Get Multiple Products method is used, for instance, to create category pages. You can include parameters for pagination, including limit, page, perPage, and offset.
Parameters
| Parameter | Details |
|---|---|
| where | ProductSearchQuery |
| with | ProductWith |
| sort | ProductSortConfig |
| pagination | PaginationState |
| campaignKey | string |
| includeSellableForFree | boolean |
| includeSoldOut | boolean |
| pricePromotionKey | string |
| minProductId | number |
Examples
All examples require a configured Storefront API client being available as client.
See Authentication for how to set up.
Get Products for Category Page
Let's say we want to create a page to list all products of a certain category with their name, color, and price range. In this case women's shirts, category id 8. We pass the category id as where parameter, the attributes color and name and priceRange as with parameter.
Sorting
We also add a sort parameter to request the products sorted from lowest to highest price.
Limit
Additionally we want to show maximum 48 products per page. This we specify in pagination.perPage. You can find more about it under Pagination.
const response = await client.products.query({
where: {
categoryId: 20201,
},
pagination: {
perPage: 48,
},
sort: {
by: APISortOption.Price,
direction: APISortOrder.Ascending,
},
with: {
attributes: {
withKey: ["brand", "name"],
},
},
});
Response
[
{
"id": 13,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:06:00+00:00",
"updatedAt": "2023-06-12T14:06:01+00:00",
"indexedAt": "2023-07-05T10:27:27+00:00",
"firstLiveAt": "2023-06-12T14:06:00+00:00",
"masterKey": "LEV003100",
"referenceKey": "LEV0031009000002",
"attributes": {
"name": {
"id": 20005,
"key": "name",
"label": "Name",
"type": "",
"multiSelect": false,
"values": { "id": 20005, "label": "Levis T-Shirt", "value": "name" }
},
"color": {
"id": 1001,
"key": "color",
"label": "Color",
"type": "",
"multiSelect": false,
"values": { "id": 41, "label": "Black", "value": "black" }
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/38ee8cd16ca9f4e7912ec4df24d1c753?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/c4a36b4e67705e7de4be766e78d0a262?quality=75&height=1067&width=800,https://cdn.aboutstatic.com/file/a95cc92",
"attributes": {}
}
],
"priceRange": {
"min": {
"currencyCode": "EUR",
"withTax": 2990,
"withoutTax": 2513,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 477, "rate": 0.19 } },
"appliedReductions": []
},
"max": {
"currencyCode": "EUR",
"withTax": 2990,
"withoutTax": 2513,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 477, "rate": 0.19 } },
"appliedReductions": []
}
},
"customData": {}
},
{
"id": 12,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:58+00:00",
"updatedAt": "2023-06-12T14:05:59+00:00",
"indexedAt": "2023-07-05T10:27:27+00:00",
"firstLiveAt": "2023-06-12T14:05:58+00:00",
"masterKey": "LEV003100",
"referenceKey": "LEV0031001002000",
"attributes": {
"color": {
"id": 1001,
"key": "color",
"label": "Color",
"type": "",
"multiSelect": false,
"values": { "id": 77, "label": "offwhite", "value": "offwhite" }
},
"name": {
"id": 20005,
"key": "name",
"label": "Name",
"type": "",
"multiSelect": false,
"values": { "id": 20005, "label": "Levis T-Shirt", "value": "name" }
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/6074e8f1a0b1cd81885a1769e5d0cfa1?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/56755a972fefe61b91380e94df8481e8?quality=75&height=1067&width=800,https://cdn.aboutstatic.com/file/4f61adf",
"attributes": {}
}
],
"priceRange": {
"min": {
"currencyCode": "EUR",
"withTax": 2990,
"withoutTax": 2513,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 477, "rate": 0.19 } },
"appliedReductions": []
},
"max": {
"currencyCode": "EUR",
"withTax": 2990,
"withoutTax": 2513,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 477, "rate": 0.19 } },
"appliedReductions": []
}
},
"customData": {}
},
{
"id": 11,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:56+00:00",
"updatedAt": "2023-06-12T14:05:57+00:00",
"indexedAt": "2023-07-05T10:27:26+00:00",
"firstLiveAt": "2023-06-12T14:05:56+00:00",
"masterKey": "LEV003100",
"referenceKey": "LEV0074002000005",
"attributes": {
"name": {
"id": 20005,
"key": "name",
"label": "Name",
"type": "",
"multiSelect": false,
"values": { "id": 20005, "label": "Levis T-Shirt", "value": "name" }
},
"color": {
"id": 1001,
"key": "color",
"label": "Color",
"type": "",
"multiSelect": false,
"values": { "id": 40, "label": "White", "value": "white" }
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/images/68bf124a0517bffaa5fe1dc7ac8707db.jpg?brightness=0.96&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/images/5464df73e16e82b6282309eac5588217.jpg?quality=75&height=1067&width=800,https://cdn.",
"attributes": {}
}
],
"priceRange": {
"min": {
"currencyCode": "EUR",
"withTax": 2990,
"withoutTax": 2513,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 477, "rate": 0.19 } },
"appliedReductions": []
},
"max": {
"currencyCode": "EUR",
"withTax": 2990,
"withoutTax": 2513,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 477, "rate": 0.19 } },
"appliedReductions": []
}
},
"customData": {}
}
]
Get Products by Brand
Here we retrieve all product of a certain brand by its brand id.
You can get all brands including their IDs as described here.
const filteredQuery = {
attributes: [
{
type: "attributes",
key: "brand",
values: [44], // ID of brand "Tom Tailor"
},
],
};
const response = await client.products.query({
where: filteredQuery,
with: {
attributes: {
withKey: ["brand"],
},
},
});
Response
{
"pagination": {
"current": 3,
"total": 3,
"perPage": 100,
"page": 1,
"first": 1,
"prev": 1,
"next": 1,
"last": 1
},
"entities": [
{
"id": 7,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:47+00:00",
"updatedAt": "2023-06-12T14:05:48+00:00",
"indexedAt": "2023-08-27T13:39:55+00:00",
"firstLiveAt": "2023-06-12T14:05:47+00:00",
"masterKey": "TOT881400",
"referenceKey": "TOT8814004000001",
"attributes": {
"brand": {
"id": 550,
"key": "brand",
"label": "Marke",
"type": "",
"multiSelect": false,
"values": { "id": 44, "label": "Tom Tailor", "value": "tom_tailor" }
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/images/838cf719621c4727f5927aa812c866cc.jpg?brightness=0.96&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/images/adee9eac06163c89dfa2eab38ff8e7cf.jpg?quality=75&height=1067&width=800,https://cdn.",
"attributes": {}
}
],
"variants": [
{
"id": 19,
"referenceKey": "TOT8814004000001_S",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:47+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 23,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 1990,
"withoutTax": 1672,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 318, "rate": 0.19 } },
"appliedReductions": []
},
"customData": { "deliveryEstimate": [] }
},
{
"id": 20,
"referenceKey": "TOT8814004000001_M",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:47+00:00",
"updatedAt": "2023-06-12T14:06:21+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 1990,
"withoutTax": 1672,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 318, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
},
{
"id": 21,
"referenceKey": "TOT8814004000001_L",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:47+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 21,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 1990,
"withoutTax": 1672,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 318, "rate": 0.19 } },
"appliedReductions": []
},
"customData": { "deliveryEstimate": [] }
}
],
"customData": {}
},
{
"id": 6,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:45+00:00",
"updatedAt": "2023-06-12T14:05:45+00:00",
"indexedAt": "2023-08-27T13:39:55+00:00",
"firstLiveAt": "2023-06-12T14:05:45+00:00",
"masterKey": "TOT881400",
"referenceKey": "TOT8814003000001",
"attributes": {
"brand": {
"id": 550,
"key": "brand",
"label": "Marke",
"type": "",
"multiSelect": false,
"values": { "id": 44, "label": "Tom Tailor", "value": "tom_tailor" }
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/images/f7268d764b2b00648da7edb8f5fb5e47.jpg?brightness=0.96&quality=75&trim=1&height=1280&width=960,https://cdn.aboutstatic.com/file/images/1bd6658e0f20367e5fc4f881e3b0b675.jpg?brightness=0.96&quality=75&height=1067&width=",
"attributes": {}
}
],
"variants": [
{
"id": 16,
"referenceKey": "TOT8814003000001_S",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:45+00:00",
"updatedAt": "2023-06-12T14:06:21+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 10,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 1990,
"withoutTax": 1672,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 318, "rate": 0.19 } },
"appliedReductions": []
},
"customData": { "deliveryEstimate": [] }
},
{
"id": 17,
"referenceKey": "TOT8814003000001_M",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:45+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 9,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 1990,
"withoutTax": 1672,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 318, "rate": 0.19 } },
"appliedReductions": []
},
"customData": { "deliveryEstimate": [] }
},
{
"id": 18,
"referenceKey": "TOT8814003000001_L",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:45+00:00",
"updatedAt": "2023-06-12T14:06:23+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 1990,
"withoutTax": 1672,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 318, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
}
],
"customData": {}
},
{
"id": 5,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:43+00:00",
"updatedAt": "2023-06-12T14:05:43+00:00",
"indexedAt": "2023-08-27T13:39:55+00:00",
"firstLiveAt": "2023-06-12T14:05:43+00:00",
"masterKey": "TOT881400",
"referenceKey": "TOT8814001000001",
"attributes": {
"brand": {
"id": 550,
"key": "brand",
"label": "Marke",
"type": "",
"multiSelect": false,
"values": { "id": 44, "label": "Tom Tailor", "value": "tom_tailor" }
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/images/7eaab7a1547c73c286d74068515fb5fc.jpg?brightness=0.96&quality=75&trim=1&height=1280&width=960,https://cdn.aboutstatic.com/file/images/0dc17517a1f6b1e75b71fb538ad36fa9.jpg?quality=75&height=1067&width=800,https://cdn.",
"attributes": {}
}
],
"variants": [
{
"id": 13,
"referenceKey": "TOT8814001000001_S",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:43+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 1990,
"withoutTax": 1672,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 318, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
},
{
"id": 14,
"referenceKey": "TOT8814001000001_M",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:43+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 6,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 1990,
"withoutTax": 1672,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 318, "rate": 0.19 } },
"appliedReductions": []
},
"customData": { "deliveryEstimate": [] }
},
{
"id": 15,
"referenceKey": "TOT8814001000001_L",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:43+00:00",
"updatedAt": "2023-06-12T14:06:21+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 45,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 1990,
"withoutTax": 1672,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 318, "rate": 0.19 } },
"appliedReductions": []
},
"customData": { "deliveryEstimate": [] }
}
],
"customData": {}
}
]
}
Get Products with Special Offers
Sale products can be retrieved by filtering for sale.
Products are considered as sale when any of its variants have a sale price on it.
const response = await client.products.query({
where: {
attributes: [{
type: 'boolean',
key: 'sale',
value: true,
}]
},
});
Response
{
"pagination": {
"current": 1,
"total": 1,
"perPage": 100,
"page": 1,
"first": 1,
"prev": 1,
"next": 1,
"last": 1
},
"entities": [
{
"id": 14,
"isActive": true,
"isSoldOut": false,
"isNew": true,
"createdAt": "2023-06-12T14:06:03+00:00",
"updatedAt": "2023-06-12T14:06:03+00:00",
"indexedAt": "2023-08-28T08:39:57+00:00",
"firstLiveAt": "2023-06-12T14:06:03+00:00",
"masterKey": "LIJ048000",
"referenceKey": "LIJ0480001000004",
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/images/bc06c53f15b5a6634e10747378fc9eb7.png?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/images/c453b9bb1b3265d8f65a4736f7631600.png?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,h"
}
],
"customData": {}
}
]
}
Get New Arrivals
New arrivals can be retrieved by filtered for isnew.
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.
const response = await client.products.query({
where: {
attributes: [{
type: 'boolean',
key: 'isNew',
value: true,
}]
},
});
Response
{
"pagination": {
"current": 1,
"total": 1,
"perPage": 100,
"page": 1,
"first": 1,
"prev": 1,
"next": 1,
"last": 1
},
"entities": [
{
"id": 14,
"isActive": true,
"isSoldOut": false,
"isNew": true,
"createdAt": "2023-06-12T14:06:03+00:00",
"updatedAt": "2023-06-12T14:06:03+00:00",
"indexedAt": "2023-08-28T08:39:57+00:00",
"firstLiveAt": "2023-06-12T14:06:03+00:00",
"masterKey": "LIJ048000",
"referenceKey": "LIJ0480001000004",
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/images/bc06c53f15b5a6634e10747378fc9eb7.png?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/images/c453b9bb1b3265d8f65a4736f7631600.png?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,h"
}
],
"customData": {}
}
]
}
Get Products within Price Range
To filter for products within a certain price range we can leverage the filters of minPrice and maxPrice.
const filteredQuery = {
minPrice: 1990,
maxPrice: 2990,
};
const response = await client.products.query({
where: filteredQuery,
});
Response
{
"pagination": {
"current": 6,
"total": 6,
"perPage": 100,
"page": 1,
"first": 1,
"prev": 1,
"next": 1,
"last": 1
},
"entities": [
{
"id": 13,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:06:00+00:00",
"updatedAt": "2023-06-12T14:06:01+00:00",
"indexedAt": "2023-08-28T09:40:02+00:00",
"firstLiveAt": "2023-06-12T14:06:00+00:00",
"masterKey": "LEV003100",
"referenceKey": "LEV0031009000002",
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/38ee8cd16ca9f4e7912ec4df24d1c753?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/c4a36b4e67705e7de4be766e78d0a262?quality=75&height=1067&width=800,https://cdn.aboutstatic.com/file/a95cc92"
}
],
"customData": {}
},
{
"id": 12,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:58+00:00",
"updatedAt": "2023-06-12T14:05:59+00:00",
"indexedAt": "2023-08-28T09:40:02+00:00",
"firstLiveAt": "2023-06-12T14:05:58+00:00",
"masterKey": "LEV003100",
"referenceKey": "LEV0031001002000",
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/6074e8f1a0b1cd81885a1769e5d0cfa1?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/56755a972fefe61b91380e94df8481e8?quality=75&height=1067&width=800,https://cdn.aboutstatic.com/file/4f61adf"
}
],
"customData": {}
},
{
"id": 11,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:56+00:00",
"updatedAt": "2023-06-12T14:05:57+00:00",
"indexedAt": "2023-08-28T09:40:02+00:00",
"firstLiveAt": "2023-06-12T14:05:56+00:00",
"masterKey": "LEV003100",
"referenceKey": "LEV0074002000005",
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/images/68bf124a0517bffaa5fe1dc7ac8707db.jpg?brightness=0.96&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/images/5464df73e16e82b6282309eac5588217.jpg?quality=75&height=1067&width=800,https://cdn."
}
],
"customData": {}
},
{
"id": 7,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:47+00:00",
"updatedAt": "2023-06-12T14:05:48+00:00",
"indexedAt": "2023-08-28T09:40:02+00:00",
"firstLiveAt": "2023-06-12T14:05:47+00:00",
"masterKey": "TOT881400",
"referenceKey": "TOT8814004000001",
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/images/838cf719621c4727f5927aa812c866cc.jpg?brightness=0.96&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/images/adee9eac06163c89dfa2eab38ff8e7cf.jpg?quality=75&height=1067&width=800,https://cdn."
}
],
"customData": {}
},
{
"id": 6,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:45+00:00",
"updatedAt": "2023-06-12T14:05:45+00:00",
"indexedAt": "2023-08-28T09:40:02+00:00",
"firstLiveAt": "2023-06-12T14:05:45+00:00",
"masterKey": "TOT881400",
"referenceKey": "TOT8814003000001",
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/images/f7268d764b2b00648da7edb8f5fb5e47.jpg?brightness=0.96&quality=75&trim=1&height=1280&width=960,https://cdn.aboutstatic.com/file/images/1bd6658e0f20367e5fc4f881e3b0b675.jpg?brightness=0.96&quality=75&height=1067&width="
}
],
"customData": {}
},
{
"id": 5,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:43+00:00",
"updatedAt": "2023-06-12T14:05:43+00:00",
"indexedAt": "2023-08-28T09:40:02+00:00",
"firstLiveAt": "2023-06-12T14:05:43+00:00",
"masterKey": "TOT881400",
"referenceKey": "TOT8814001000001",
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/images/7eaab7a1547c73c286d74068515fb5fc.jpg?brightness=0.96&quality=75&trim=1&height=1280&width=960,https://cdn.aboutstatic.com/file/images/0dc17517a1f6b1e75b71fb538ad36fa9.jpg?quality=75&height=1067&width=800,https://cdn."
}
],
"customData": {}
}
]
}
Get Related Products
Related products are groups of product with the same core criteria, i.e., share the same attributes like T-shirts of different colors and sizes. Each product of a group shares the same style key attribute. #
In this example we fetch related products for a specific t-shirt which has the style key THS090600.
const filteredQuery = {
attributes: [
{
type: "attributes",
key: "styleKey",
values: ["THS090600"],
},
],
};
const response = await client.products.query({
where: filteredQuery,
});
Response
{
"pagination": {
"current": 4,
"total": 4,
"perPage": 100,
"page": 1,
"first": 1,
"prev": 1,
"next": 1,
"last": 1
},
"entities": [
{
"id": 4,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:41+00:00",
"updatedAt": "2023-06-12T14:05:41+00:00",
"indexedAt": "2023-08-30T12:40:03+00:00",
"firstLiveAt": "2023-06-12T14:05:41+00:00",
"masterKey": "THS090600",
"referenceKey": "THS1561003000001",
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/dac81f069b3f7bcea884c806726d5188?bg=F4F4F5&quality=75&trim=1&height=1067&width=800, https://cdn.aboutstatic.com/file/images/9b955c9d77708548b0d8486f306e0132.jpg?quality=75&height=1067&width=800, https://cdn.aboutstatic.com"
}
],
"customData": {}
},
{
"id": 3,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:38+00:00",
"updatedAt": "2023-06-12T14:05:39+00:00",
"indexedAt": "2023-08-30T12:40:03+00:00",
"firstLiveAt": "2023-06-12T14:05:38+00:00",
"masterKey": "THS090600",
"referenceKey": "THS0906007000001",
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/9692f6858f7e017f50861290cbb424c4?bg=F4F4F5&quality=75&trim=1&height=1280&width=960, https://cdn.aboutstatic.com/file/1ac0057101b527a9d4340379feededfb?quality=75&height=1067&width=800, https://cdn.aboutstatic.com/file/34800"
}
],
"customData": {}
},
{
"id": 2,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:36+00:00",
"updatedAt": "2023-06-12T14:05:37+00:00",
"indexedAt": "2023-08-30T12:40:03+00:00",
"firstLiveAt": "2023-06-12T14:05:36+00:00",
"masterKey": "THS090600",
"referenceKey": "THS0906006000001",
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/8de1d6ebb091d7363a05bcf99a0095f3?quality=75&height=1067&width=800,https://cdn.aboutstatic.com/file/1894bfbbfec69306940eb79ee3c6c8f4?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,"
}
],
"customData": {}
},
{
"id": 1,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:05:34+00:00",
"indexedAt": "2023-08-30T12:40:03+00:00",
"firstLiveAt": "2023-06-12T14:05:33+00:00",
"masterKey": "THS090600",
"referenceKey": "THS0906008000001",
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/cd81a5d37e4241686586812d9e179553?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/1c98f7fc408b9d2cca91abfbf5650df1?bg=F4F4F5&quality=75&height=1067&width=800, https://cdn.aboutstatic.com/f"
}
],
"customData": {}
}
]
}
Filter Products by Attributes
SCAYLE’s powerful search function enables the user to search for product information. The search index can process complex search queries within a short time to fulfill essential shop requirements. The products endpoint's with parameter, as used to get multiple Products, supports two different kinds of parameters:
Queries for standard properties that are always present on a product (e.g. category, price range but also texts like name and description). Queries for product attributes that are defined by and specific to each shop instance.
Example
All examples require a configured Storefront API client being available as client.
See Authentication for how to set up.
In this example we are building a filter for our women's shirts category page. This can be divided into two steps:
Showing all available filters for the current category Applying selected filters to our products query
Before we can start we need to manually add a filter to our demo data via the SCAYLE Panel. \
Once the filters are set in the SCAYLE Panel we can proceed with the actual querying.
Step 1: Get all available Filters
To find all existing filters of our current category's products we use the filters API and pass the category id as with parameter.
This will return us a list of attributes we can filter by. In our shop UI we would list these for our users to select.
// Get available filters for our category
const options = {
where: {
categoryId: 8,
},
};
const filters = await client.filters.get(options);
const colorFilter = filters.find((filter) => filter.slug === "color");
console.log(colorFilter.values.map((filter) => filter.name));
// [ 'White', 'black', 'offwhite' ]
Response
[
{
"id": null,
"slug": "prices",
"name": "Prices",
"attributeGroupType": "computed_attribute",
"type": "range",
"values": [{ "min": 2990, "max": 2990, "productCount": 3 }]
},
{
"id": null,
"slug": "sale",
"name": "Sale",
"attributeGroupType": "computed_attribute",
"type": "boolean",
"values": [
{ "name": false, "productCount": 3 },
{ "name": true, "productCount": 0 }
]
},
{
"id": null,
"slug": "max_savings_percentage",
"name": "Savings",
"attributeGroupType": "computed_attribute",
"type": "range",
"values": [{ "min": 0, "max": 0, "productCount": 3 }]
},
{
"id": 1001,
"slug": "color",
"name": "Farbe",
"attributeGroupType": "",
"type": "attributes",
"values": [
{ "name": "Weiß", "productCount": 1, "id": 40, "value": "weiss" },
{ "name": "Schwarz", "productCount": 1, "id": 41, "value": "schwarz" },
{ "name": "offwhite", "productCount": 1, "id": 77, "value": "offwhite" }
]
}
]
Step 2: Apply an Attribute Filter to the Product Search
We pick the color attribute filter and use its first value to refine your product search. In this case "White".
In a user-facing application, you might want to display all filters on the screen and then have the user select their desired filters and values.
// Get filtered product results
// Variables colorFilter and options are based on step 1
const filteredQuery = {
...options,
attributes: [
{
type: "attributes",
key: colorFilter.slug,
values: [colorFilter.values[0].id], // ID of color "white"
},
],
};
const response = await client.products.query({
where: filteredQuery,
with: {
variants: "all",
attributes: {
withKey: ["color"],
},
},
});
console.log(response.entities[0].attributes.color.values.label);
// White
The products API returns paginated results. You can see here how to build a pagination.
To include additional properties in the response, use the with parameter.
We recommend that you update the website URL with the applied filters. This makes it easier for your users to bookmark the URL and revisit your shop with prefiltered results.
Response
{
"pagination": {
"current": 2,
"total": 2,
"perPage": 100,
"page": 1,
"first": 1,
"prev": 1,
"next": 1,
"last": 1
},
"entities": [
{
"id": 11,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:56+00:00",
"updatedAt": "2023-06-12T14:05:57+00:00",
"indexedAt": "2023-07-06T08:12:40+00:00",
"firstLiveAt": "2023-06-12T14:05:56+00:00",
"masterKey": "LEV003100",
"referenceKey": "LEV0074002000005",
"attributes": {
"color": {
"id": 1001,
"key": "color",
"label": "Farbe",
"type": "",
"multiSelect": false,
"values": { "id": 40, "label": "Weiß", "value": "weiss" }
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/images/68bf124a0517bffaa5fe1dc7ac8707db.jpg?brightness=0.96&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/images/5464df73e16e82b6282309eac5588217.jpg?quality=75&height=1067&width=800,https://cdn.",
"attributes": {}
}
],
"variants": [
{
"id": 31,
"referenceKey": "LEV0074002000005_S",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:56+00:00",
"updatedAt": "2023-06-12T14:06:24+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 40,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 2990,
"withoutTax": 2513,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 477, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
},
{
"id": 32,
"referenceKey": "LEV0074002000005_M",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:56+00:00",
"updatedAt": "2023-06-12T14:06:23+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 41,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 2990,
"withoutTax": 2513,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 477, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
},
{
"id": 33,
"referenceKey": "LEV0074002000005_L",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:56+00:00",
"updatedAt": "2023-06-12T14:06:23+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 42,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 2990,
"withoutTax": 2513,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 477, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
}
],
"customData": {}
},
{
"id": 2,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:36+00:00",
"updatedAt": "2023-06-12T14:05:37+00:00",
"indexedAt": "2023-07-06T08:12:40+00:00",
"firstLiveAt": "2023-06-12T14:05:36+00:00",
"masterKey": "THS090600",
"referenceKey": "THS0906006000001",
"attributes": {
"color": {
"id": 1001,
"key": "color",
"label": "Farbe",
"type": "",
"multiSelect": false,
"values": { "id": 40, "label": "Weiß", "value": "weiss" }
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/8de1d6ebb091d7363a05bcf99a0095f3?quality=75&height=1067&width=800,https://cdn.aboutstatic.com/file/1894bfbbfec69306940eb79ee3c6c8f4?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,",
"attributes": {}
}
],
"variants": [
{
"id": 4,
"referenceKey": "THS0906006000001_S",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:36+00:00",
"updatedAt": "2023-06-12T14:06:23+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 34,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
},
{
"id": 5,
"referenceKey": "THS0906006000001_M",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:36+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 11,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
},
{
"id": 6,
"referenceKey": "THS0906006000001_L",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:36+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 36,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
}
],
"customData": {}
}
]
}
Additional: Get single filter values
It is also possible to get possible values and their product counts of a single filter. In the following example we want to get all values from color filter.
// Get all color values and their product counts
const options = {
category: 8,
};
const response = await client.filters.getValues("color", {
where: options,
});
console.log(response[0].name);
// Black
Response
[
{ "name": "Schwarz", "productCount": 5, "id": 41, "value": "schwarz" },
{ "name": "Weiß", "productCount": 2, "id": 40, "value": "weiss" },
{
"name": "Graumeliert",
"productCount": 2,
"id": 42,
"value": "graumeliert"
},
{ "name": "Dunkelblau", "productCount": 2, "id": 9, "value": "dunkelblau" },
{ "name": "Dunkelgrau", "productCount": 1, "id": 43, "value": "dunkelgrau" },
{ "name": "Hellblau", "productCount": 1, "id": 51, "value": "hellblau" },
{ "name": "offwhite", "productCount": 1, "id": 77, "value": "offwhite" }
]
Filter Products by Search Term
This functionality allows user to search products based on a word or a phrase. For example, user may want to search for a 'Blue Sweater'. This functionality is explained in the Search section. Refer to Search by term for understanding the usability and functionality.
Pagination
For listing a large set of products multiple page-wise requests need to be made. This can be achieved by using different Pagination parameters as seen in the example above.
For more details on this topic refer to Pagination.
Filter Products by Attributes
SCAYLE’s powerful search function enables the user to search for product information. The search index can process complex search queries within a short time to fulfill essential shop requirements.
The products endpoint's where parameter, as used to get multiple Products, supports two different kinds of parameters:
- Queries for standard properties that are always present on a product (e.g. category, price range but also texts like name and description).
- Queries for product attributes that are defined by and specific to each shop instance.
Example
All examples require a configured Storefront API client being available as client.
See Authentication for how to set up.
In this example we are building a filter for our women's shirts category page. This can be divided into two steps:
- Showing all available filters for the current category
- Applying selected filters to our products query
Before we can start we need to manually add a filter to our demo data via the SCAYLE Panel.
Create filters in SCAYLE Panel
In this example we just add a color filter for the root category "Women". Filters are automatically added to its children categories as well. So the filter is also applied to the sub-category women's shirts.
- In the SCAYLE Panel go to your shop.
- In the sidebar select
Products > Categories. - Choose the category to add the filters to, e.g. "Women".
- Switch to filters tab
- Click + Add Filter and select a filter, e.g. color.
- Press save to apply the changes.
Now we can proceed with the actual querying.
Step 1: Get all available Filters
To find all existing filters of our current category's products we use the filters API and pass the category id as where parameter.
This will return us a list of attributes we can filter by. In our shop UI we would list these for our users to select.
// Get available filters for our category
const options = {
where: {
categoryId: 8,
},
};
const filters = await client.filters.get(options);
const colorFilter = filters.find((filter) => filter.slug === "color");
console.log(colorFilter.values.map((filter) => filter.name));
// [ 'White', 'Bleck', 'Offwhite' ]
Response
[
{
"id": null,
"slug": "prices",
"name": "Prices",
"attributeGroupType": "computed_attribute",
"type": "range",
"values": [{ "min": 2990, "max": 2990, "productCount": 3 }]
},
{
"id": null,
"slug": "sale",
"name": "Sale",
"attributeGroupType": "computed_attribute",
"type": "boolean",
"values": [
{ "name": false, "productCount": 3 },
{ "name": true, "productCount": 0 }
]
},
{
"id": null,
"slug": "max_savings_percentage",
"name": "Savings",
"attributeGroupType": "computed_attribute",
"type": "range",
"values": [{ "min": 0, "max": 0, "productCount": 3 }]
},
{
"id": 1001,
"slug": "color",
"name": "Color",
"attributeGroupType": "",
"type": "attributes",
"values": [
{ "name": "White", "productCount": 1, "id": 40, "value": "white" },
{ "name": "Black", "productCount": 1, "id": 41, "value": "black" },
{ "name": "offwhite", "productCount": 1, "id": 77, "value": "offwhite" }
]
}
]
Step 2: Apply an Attribute Filter to the Product Search
We pick the color attribute filter and use its first value to refine your product search. In this case "White".
In a user-facing application, you might want to display all filters on the screen and then have the user select their desired filters and values.
// Get filtered product results
// Variables colorFilter and options are based on step 1
const filteredQuery = {
...options,
attributes: [
{
type: "attributes",
key: colorFilter.slug,
values: [colorFilter.values[0].id], // ID of color "weiß"
},
],
};
const response = await client.products.query({
where: filteredQuery,
with: {
variants: "all",
attributes: {
withKey: ["color"],
},
},
});
console.log(response.entities[0].attributes.color.values.label);
// Weiß
The products API returns paginated results.
To include additional properties in the response, use the with parameter.
We recommend that you update the website URL with the applied filters. This makes it easier for your users to bookmark the URL and revisit your shop with prefiltered results.
Response
{
"pagination": {
"current": 2,
"total": 2,
"perPage": 100,
"page": 1,
"first": 1,
"prev": 1,
"next": 1,
"last": 1
},
"entities": [
{
"id": 11,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:56+00:00",
"updatedAt": "2023-06-12T14:05:57+00:00",
"indexedAt": "2023-07-06T08:12:40+00:00",
"firstLiveAt": "2023-06-12T14:05:56+00:00",
"masterKey": "LEV003100",
"referenceKey": "LEV0074002000005",
"attributes": {
"color": {
"id": 1001,
"key": "color",
"label": "Farbe",
"type": "",
"multiSelect": false,
"values": { "id": 40, "label": "Weiß", "value": "weiss" }
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/images/68bf124a0517bffaa5fe1dc7ac8707db.jpg?brightness=0.96&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/images/5464df73e16e82b6282309eac5588217.jpg?quality=75&height=1067&width=800,https://cdn.",
"attributes": {}
}
],
"variants": [
{
"id": 31,
"referenceKey": "LEV0074002000005_S",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:56+00:00",
"updatedAt": "2023-06-12T14:06:24+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 40,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 2990,
"withoutTax": 2513,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 477, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
},
{
"id": 32,
"referenceKey": "LEV0074002000005_M",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:56+00:00",
"updatedAt": "2023-06-12T14:06:23+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 41,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 2990,
"withoutTax": 2513,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 477, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
},
{
"id": 33,
"referenceKey": "LEV0074002000005_L",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:56+00:00",
"updatedAt": "2023-06-12T14:06:23+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 42,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 2990,
"withoutTax": 2513,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 477, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
}
],
"customData": {}
},
{
"id": 2,
"isActive": true,
"isSoldOut": false,
"isNew": false,
"createdAt": "2023-06-12T14:05:36+00:00",
"updatedAt": "2023-06-12T14:05:37+00:00",
"indexedAt": "2023-07-06T08:12:40+00:00",
"firstLiveAt": "2023-06-12T14:05:36+00:00",
"masterKey": "THS090600",
"referenceKey": "THS0906006000001",
"attributes": {
"color": {
"id": 1001,
"key": "color",
"label": "Farbe",
"type": "",
"multiSelect": false,
"values": { "id": 40, "label": "Weiß", "value": "weiss" }
}
},
"images": [
{
"hash": "https://cdn.aboutstatic.com/file/8de1d6ebb091d7363a05bcf99a0095f3?quality=75&height=1067&width=800,https://cdn.aboutstatic.com/file/1894bfbbfec69306940eb79ee3c6c8f4?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,",
"attributes": {}
}
],
"variants": [
{
"id": 4,
"referenceKey": "THS0906006000001_S",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:36+00:00",
"updatedAt": "2023-06-12T14:06:23+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 34,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
},
{
"id": 5,
"referenceKey": "THS0906006000001_M",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:36+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 11,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
},
{
"id": 6,
"referenceKey": "THS0906006000001_L",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:36+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 36,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {}
}
],
"customData": {}
}
]
}
Additional: Get Single Filter Values
It is also possible to get possible values and their product counts of a single filter. In the following example we want to get all values from color filter.
// Get all color values and their product counts
const options = {
category: 8,
};
const response = await client.filters.getValues("color", {
where: options,
});
console.log(response[0].name);
// Schwarz
List Variants
When retrieving multiple variants by their IDs, you can specify their properties like stock and also retrieve prices relevant to a particular campaign or promotion.
Parameters
| Parameter | Type | Details |
|---|---|---|
| variantsIds | Number[] | IDs of the variants to retrieve. |
| with | VariantWith | Contained as with inside the options object (second parameter). |
| campaignKey | String | Used to get the correct prices for the specified campaign. |
| pricePromotionkey | String | Adjust variant price based on the specified pricePromotionKey. If the variant does not have a matching price promotion, the default price is returned. |
Example
All examples require a configured Storefront API client being available as client.
See Authentication for how to set up.
Get Variants
From one of our previous examples we know the variant IDs (1, 2, 3) of a specific shirt. Now we want to query all additional data for these variants as well as all stock information.
// Get stock information of multiple variants
const variants = await client.variants.getByIds([1, 2, 3], {
with: {
attributes: "all",
stock: "all",
},
});
console.log(variants[0].stock.quantity);
// 31
Response
[
{
"id": 1,
"referenceKey": "THS0906008000001_S",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:06:21+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 31,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {},
"productId": 1
},
{
"id": 2,
"referenceKey": "THS0906008000001_M",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:06:21+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 0,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {},
"productId": 1
},
{
"id": 3,
"referenceKey": "THS0906008000001_L",
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 0,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3990,
"withoutTax": 3353,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 637, "rate": 0.19 } },
"appliedReductions": []
},
"customData": {},
"productId": 1
}
]
Get Reduced Campaign Prices
Sometimes we have an active price campaign running. When we pass its campaignKey we get adjusted prices based on the campaigns reduction:
const variants = await client.variants.getByIds([1, 2, 3], {
with: {
attributes: "all",
stock: "all",
},
campaignKey: "promo_test_20",
});
const price = variants[0].price;
const savings = price.appliedReductions[0].amount.absoluteWithTax;
const oldPrice = savings + price.withTax;
console.log(`Price: ${price.withTax}`);
console.log(`Savings: ${savings}`);
console.log(`Previous Price: ${oldPrice}`);
// Price: 3192
// Savings: 798
// Previous Price: 3990
Response
[
{
"id": 1,
"referenceKey": "THS0906008000001_S",
"attributes": {
"size": {
"id": 1002,
"key": "size",
"label": "Size",
"type": "",
"multiSelect": false,
"values": { "id": 28, "label": "S", "value": "s" }
}
},
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-08-28T11:19:33+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 31,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3192,
"withoutTax": 2682,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 510, "rate": 0.19 } },
"appliedReductions": [
{
"category": "campaign",
"type": "relative",
"amount": { "relative": 0.2, "absoluteWithTax": 798 }
}
]
},
"customData": { "deliveryEstimate": [] },
"productId": 1
},
{
"id": 2,
"referenceKey": "THS0906008000001_M",
"attributes": {
"size": {
"id": 1002,
"key": "size",
"label": "Size",
"type": "",
"multiSelect": false,
"values": { "id": 29, "label": "M", "value": "m" }
}
},
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-08-28T11:19:33+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3192,
"withoutTax": 2682,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 510, "rate": 0.19 } },
"appliedReductions": [
{
"category": "campaign",
"type": "relative",
"amount": { "relative": 0.2, "absoluteWithTax": 798 }
}
]
},
"customData": {},
"productId": 1
},
{
"id": 3,
"referenceKey": "THS0906008000001_L",
"attributes": {
"size": {
"id": 1002,
"key": "size",
"label": "Size",
"type": "",
"multiSelect": false,
"values": { "id": 30, "label": "L", "value": "l" }
}
},
"firstLiveAt": "0001-01-01T00:00:00+00:00",
"createdAt": "2023-06-12T14:05:33+00:00",
"updatedAt": "2023-06-12T14:06:22+00:00",
"stock": {
"supplierId": 1,
"warehouseId": 1,
"quantity": 0,
"isSellableWithoutStock": false
},
"price": {
"currencyCode": "EUR",
"withTax": 3192,
"withoutTax": 2682,
"recommendedRetailPrice": null,
"tax": { "vat": { "amount": 510, "rate": 0.19 } },
"appliedReductions": [
{
"category": "campaign",
"type": "relative",
"amount": { "relative": 0.2, "absoluteWithTax": 798 }
}
]
},
"customData": {},
"productId": 1
}
]
