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.
Set Sorting Attributes
- Go to the just created attribute group
variantSorting
- Under attributes add five attributes with values from 1 to 5.
Map Sizes to variantSorting
- Go to attribute group
Größe
orSizes
and 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…
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.