docs
  1. SCAYLE Resource Center
  2. Developer Guides
  3. Products
  4. Using Products in your Store

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

ParameterDetails
productId

Integer

ID of the product.

with

Object

Used to request the optional fields. Possible keys: variants, attributes, siblings.

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

  1. In the SCAYLE Panel go to Settings > Products Structure > Attributes
  2. Click + Add Attribute Group.
  3. Set a name and frontend name, e.g. variantSorting.
  4. Set Entity level to variant.
  5. Check the box for Relevant for mapping
  6. Click Save.

Set Sorting Attributes

  1. Go to the just created attribute group variantSorting
  2. Under attributes add five attributes with values from 1 to 5.

Map Sizes to variantSorting

  1. Go to attribute group Größe or Sizes and select Mapping
  2. Click New Mapping and select variantSorting
  3. 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:

  1. Download demoPrices.csv
  2. In the SCAYLE Panel go to Settings
  3. In the sidebar open Imports & Jobs -> Imports
  4. Click +New Import
  5. In the now opened modal select Overwrite Merchant Prices
  6. Click Choose File and select the downloaded CSV file
  7. Click Validate and Confirm
  8. Proceed to Scheduling and submit to a user to review
  9. 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

ParameterDetails
whereProductSearchQuery
withProductWith
sortProductSortConfig
paginationPaginationState
campaignKeystring
includeSellableForFreeboolean
includeSoldOutboolean
pricePromotionKeystring
minProductIdnumber

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": {}
    }
  ]
}

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.