Configurable Products

General

Configurable products allow you to combine a mainItem with multiple subItems. Use cases are products that require flexible customization and configuration. For example:

Correctional glasses: the frame (main item) can be configured with lenses, blue light filter, or other options (as subitems).
Personalized jerseys: the basic jersey (main item) can be customized with a name, number, and logos (as subitems).
Customized sofas: the sofa (main item) with extras such as cushions (as subitems).

Configurable products can be freely configured based on individual variants. This allows for great flexibility, since all possible combinations do not need to be created upfront.

Configurable vs composite products

Configurable products are created in the Storefront API. Composite products are pre-defined products composed of other products. Composite products are created outside of SCAYLE and imported via Admin-API.

Storefront API

Create configurable products

To create configurable products, mainItems and subItems are set up as products and variants in SCAYLE.

A configuration flow (or rule set) is applied to the shop application that customizes how items and subitems are displayed and interact in the frontend. Based on the rule set, it is possible that subItems can also be bought individually.

Rule Set

The rule set on which combinations of products can be configured needs to be connected with the shop application. As this application creates the configured products on the Add Item to Basket request.

If the rule sets are relatively simple they can be added directly to the shop application. However, for more complex sets it might be appropriate to use a shop application backend or separate middleware.

Within the configuration flow, the shop application needs to check if the individual items are available and determine whether they can or cannot be used.

Implementation

For the Storefront API SDK, version 14.x or later is required.

When using the Storefront API SDK, you can still use the bapiClient.basket.addOrUpdateItems function, but you need to enable the feature flag for using the itemGroupId.

If you do not use the SDK and you want to update an item, you need to identify the correct itemKey on the basket by checking for the variantId and the matching itemGroupId.

Add items to the basket

For adding or updating items for configurable products you need to set the itemGroup property with all three mandatory keys:

key	description	possible values
`id`	Used to group the items belonging to the same configurable product.	String with max. 8 letters
`isMainItem`	Defines the main item which is used also as the image there can only be one main item per `itemGroup`.	true, false
`isRequired`	If an item with `isRequired=true` becomes unavailable, the complete `itemGroup` is set as unavailable (the `mainItem` always needs to be true).	true, false

Response

{
    "quantity": 1,
    "variantId": 143018,
    "itemGroup":
    {
        "id": "Bm3D7D85",
        "isMainItem": false,
        "isRequired": true
    }
}

Delete an item from the basket

The Storefront API Remove an item from a basket endpoint already depends on the item.key of the basket for deletion.

Identify the key by checking for the variantId and the matching itemGroupId.

Check the Storefront API Reference for more details.

Availability

The API will automatically set unavailable items as unavailable.
If an item of a configurable product gets unavailable (i.e., "isRequired": true) all items of the configurable product are automatically set as unavailable.

Order Success Page & MyAccount area

On the order success page and in the MyAccount area you will be using the Checkout.

Here, the itemGroup property will be provided for each item (items.[].itemGroup.id) and the shop application needs to group all items of a configurable product in order to display it appropriately.

This method requires configured Storefront API client being available as client.

Add configurable glasses to basket

In this example we are going to add a pair of configured glasses to our basket. Our product consists of a frame with variant id 1 and a blue light filter as a feature with variant id 42. Also we want to add another pair of configured, lets say sunglasses. With the exact same frame but instead of blue light filtered glasses we decide for brown colored glasses, variant id 69.

Only possible with NodeJS SDK.

const blueGlasses = [
  {
    variantId: 1, quantity: 1, params: {
      itemGroup: { id: "blue_glasses_abfhs7", isMainItem: true, isRequired: true },
    },
  },
  {
    variantId: 42, quantity: 1, params: {
      itemGroup: { id: "blue_glasses_abfhs7", isMainItem: false, isRequired: true },
    },
  },
]
const sunGlasses = [
  {
    variantId: 1, quantity: 1, params: {
      itemGroup: { id: "sun_glasses_hhbdz6", isMainItem: true, isRequired: true },
    },
  },
  {
    variantId: 69, quantity: 1, params: {
      itemGroup: { id: "sun_glasses_hhbdz6", isMainItem: false, isRequired: true },
    },
  },
]

const response = await client.basket.addOrUpdateItems("myshop_customer_1234", [
  ...blueGlasses,
  ...sunGlasses
]);

Response

{
    "itemGroup":
    {
        "id": "30820546",
        "isMainItem": false,
        "isRequired": true
    }
}