Extend Entity Data

General

Custom data allows storing arbitrary data on various entities according to the defined rules in the Custom Data Configuration.

You can add and manage the custom data directly in the SCAYLE Panel or via the Admin API.
Custom data usage is enlisted below:

This data is then returned via Storefront API.

You can use custom data to control and store:

Guidelines on categories
Shop-country-specific configurations
Content elements in your shop
- Listings
- Commercials/Ads
- Configure ID's for paybacks
- Special banners
- SEO information. It gives you many more options to add to shop entity data

Operations

Create or update your entity custom data using the Create Or Update Custom Data method.
Create or update your entity custom data for a specific key using the Create Or Update Custom Data for Specific Key method.
Get your entity custom data using the Get Custom Data method.
Get your entity custom data for a specific key using the Get Custom Data for Specific Key method.
Delete your entity custom data using the Delete Custom Data method.
Delete your entity custom data for a specific key using the Delete Custom Data for Specific Key method.

Custom data configurations

Custom data configurations are rules defining the allowed schema for the custom data making use of a specific entity.

Custom Data Configuration Entity

Parameter	Details
properties	CustomDataConfigProperty Collection of custom configuration properties.

Parameter

Details

properties

CustomDataConfigProperty

Collection of custom configuration properties.

Custom Data Configuration Properties

Each custom data configuration consists of properties with the following:

name: Name of the property.
type: Type of the property , e.g., string.
isLocalized: Whether the property is localized or not.
defaultValue: Default value for the property. Having null as default value means there is no default value specified, not that it should be set to null.
rules: A collection of rules applying to the corresponding entity custom data property.
inherit: Whether the property is inheritable or not depends on entities having parent entities or being self-referencing like in the case of categories.

Custom Data Configuration Property Rules

Allowed values:

minLength: Specifies the minimum length for a property value. This is only supported for properties of the type string.
maxLength: Specifies the maximum length for a property value. This is only supported for properties of the type string.
requiredLocales: Specifies the localization values of a property, e.g.,: [de_DE, en_EN]. This is only supported for properties of the type string.
required: Whether the property is required or not in the custom data schema. E.g. property must exist as a part of custom data of an entity
jsonSchema: Whether the property can hold a custom JSON schema or not. This is only supported for properties of the type json.

Behaviour table of Required rule and Default value

Required	Required
Default value	TRUE	FALSE
NULL	custom data property must be provided	providing custom data property is optional
NOT NULL	entity can be created without custom data property; the default value is being used	entity can be created without custom data property; the default value is being used

Operations

Create your custom data configuration using the Create Custom Data Configuration method.
Update your custom data configuration using the Update Custom Data Configuration method.
Get your custom data configuration using the Get Custom Data Configuration method.
Delete your custom data configuration using the Delete Custom Data Configuration method.

Providing an entity is mandatory for all operations.

Available entities are:
- shop
- brand
- shopCountry
- shopCategory
- shopCategoryCountry
- product
- productVariant
- campaign

Operations Overlapping

In order to ensure the consistency of the custom data, applying parallel create/update/delete operation over the same entity is not allowed.

Admin API

Create Or Update Custom Data

When updating or creating custom data, you must specify additional parameters defining where you need to preserve the operation payload. You can create custom data for different entities. These are

Brands
Campaigns
Products
Shops
Shop Countries
Shop Categories
Shop Country Categories
Variants

This method is used to create or update custom data.

It is not possible to create/update custom data without an existing custom data configuration.
The maximum length for a string or json field is 7,000 characters.
Type casting for boolean is applied.
- Accepted values are "true", "false", true, false, 1, 0.
The maximum depth of a JSON object is 4 levels.

await adminApi.apis.ShopCustomData.createOrUpdateShopCustomData({shopKey: shopKey}, {requestBody: customData});
await adminApi.apis.BrandCustomData.createOrUpdateBrandCustomData({brandId: brandId}, {requestBody: customData});
await client.apis.ShopCategoriesCustomData.createOrUpdateShopCategoriesCustomData({shopKey: shopKey, shopCategoryId: shopCategoryId}, {requestBody: customData});
await adminApi.apis.ShopCategoriesCountryCustomData.createOrUpdateShopCategoriesCountryCustomData({shopKey: shopKey, shopCategoryId: shopCategoryId, countryCode: countryCode}, {requestBody: customData});
await adminApi.apis.ShopCountryCustomData.createOrUpdateShopCountryCustomData({shopKey: shopKey, countryCode: countryCode}, {requestBody: customData});
await adminApi.apis.ProductCustomData.createOrUpdateProductCustomData({productIdentifier: productIdentifier}, {requestBody: customData});
await adminApi.apis.ProductVariantCustomData.createOrUpdateProductVariantCustomData({variantIdentifier: variantIdentifier}, {requestBody: customData});
await adminApi.apis.CampaignCustomData.createOrUpdateCampaignCustomData({campaignId: campaignId}, {requestBody: customData});

Parameter

Parameter	Details
isValid	Boolean A sample key for a boolean value of custom data
score	Integer A sample key for a integer value of custom data
name	String A sample key for a string value of custom data
localizedColor	Object A sample key for a string value scoped by locale
sampleJson	Object A sample key for a json value

Create or Update Custom Data

let customData = {
    isValid: true,
    score: 10,
    name: "empco-de",
    localizedColor: {
        de_DE: "White"
    },
    sampleJson: {
        foo: {
           "bar" : "value"
        }
    }
};

await adminApi.apis.ShopCustomData.createOrUpdateShopCustomData({shopKey: 'ms'}, {requestBody: customData});
await adminApi.apis.BrandCustomData.createOrUpdateBrandCustomData({brandId: 5038}, {requestBody: customData});
await adminApi.apis.ShopCategoriesCustomData.createOrUpdateShopCategoriesCustomData({shopKey: 'ms', shopCategoryId: 112}, {requestBody: customData});
await adminApi.apis.ShopCategoriesCountryCustomData.createOrUpdateShopCategoriesCountryCustomData({shopKey: 'ms', shopCategoryId: 112, countryCode: 'DE'}, {requestBody: customData});
await adminApi.apis.ShopCountryCustomData.createOrUpdateShopCountryCustomData({shopKey: 'ms', countryCode: 'DE'}, {requestBody: customData});
await adminApi.apis.ProductCustomData.createOrUpdateProductCustomData({productIdentifier: 1}, {requestBody: customData});
await adminApi.apis.ProductVariantCustomData.createOrUpdateProductVariantCustomData({variantIdentifier: 1}, {requestBody: customData});
await adminApi.apis.CampaignCustomData.createOrUpdateCampaignCustomData({campaignId: 1}, {requestBody: customData});

Create or Update Custom Data for a Specific Key

When updating or creating a custom data for a specific key, you must specify additional parameters defining where you need to preserve the operation payload.

This method is used to create or update custom data for a specific key.

It is not possible to create/update custom data without an existing custom data configuration. The maximum length for a string or json field is 7,000 characters. Type casting for boolean is applied.

Accepted values are "true", "false", true, false, 1, 0. The maximum depth of a JSON object is 4 levels.

await adminApi.apis.ShopCustomData.createOrUpdateShopCustomDataForKey({shopKey: shopKey, key: key}, {requestBody: customData});
await adminApi.apis.BrandCustomData.createOrUpdateBrandCustomDataForKey({brandId: brandId, key: key}, {requestBody: customData});
await adminApi.apis.ShopCategoriesCustomData.createOrUpdateShopCategoriesCustomDataForKey({shopKey: shopKey, shopCategoryId: shopCategoryId, key: key}, {requestBody: customData});
await adminApi.apis.ShopCategoriesCountryCustomData.createOrUpdateShopCategoriesCountryCustomDataForKey({shopKey: shopKey, shopCategoryId: shopCategoryId, key: key}, {requestBody: customData});
await adminApi.apis.ShopCountryCustomData.createOrUpdateShopCountryCustomDataForKey({shopKey: shopKey, countryCode: countryCode, key: key}, {requestBody: customData});
await adminApi.apis.ProductCustomData.createOrUpdateProductCustomDataForKey({productIdentifier: productIdentifier, key: key}, {requestBody: customData});
await adminApi.apis.ProductVariantCustomData.createOrUpdateProductVariantCustomDataForKey({variantIdentifier: variantIdentifier, key: key}, {requestBody: customData});
await adminApi.apis.CampaignCustomData.createOrUpdateCampaignCustomDataForKey({campaignId: campaignId}, {key: key}, {requestBody: customData});

Parameter	Details
isValid	Boolean A sample key for a boolean value of custom data
score	Integer A sample key for a integer value of custom data
name	String A sample key for a string value of custom data
localizedColor	Object A sample key for a string value scoped by locale
sampleJson	Object A sample key for a json value

Examples

let customData = {
    isValid: true
};

await AdminApi.apis.ShopCustomData.createOrUpdateShopCustomDataForKey({shopKey: 'ms', key: 'isValid'}, {requestBody: customData});
await AdminApi.apis.BrandCustomData.createOrUpdateBrandCustomDataForKey({brandId: 5038, key: 'isValid'}, {requestBody: customData});
await AdminApi.apis.ShopCategoriesCustomData.createOrUpdateShopCategoriesCustomDataForKey({shopKey: 'ms', shopCategoryId: 112, key: 'isValid'}, {requestBody: customData});
await AdminApi.apis.ShopCategoriesCountryCustomData.createOrUpdateShopCategoriesCountryCustomDataForKey({shopKey: 'ms', shopCategoryId: 112, countryCode: 'DE', key: 'isValid'}, {requestBody: customData});
await AdminApi.apis.ShopCountryCustomData.createOrUpdateShopCountryCustomDataForKey({shopKey: 'ms', countryCode: 'DE', key: 'isValid'}, {requestBody: customData});
await AdminApi.apis.ProductCustomData.createOrUpdateProductCustomDataForKey({productIdentifier: 1, key: 'isValid'}, {requestBody: customData});
await AdminApi.apis.ProductVariantCustomData.createOrUpdateProductVariantCustomDataForKey({variantIdentifier: 1, key: 'isValid'}, {requestBody: customData});
await AdminApi.apis.CampaignCustomData.createOrUpdateCampaignCustomDataForKey({campaignId: 300, key: 'isValid'}, {requestBody: customData});

Get Custom Data

When retrieving custom data, you must specify additional parameters defining the entity/record where you need to perform such operation.

This method is used to get custom data.

await AdminApi.apis.BrandCustomData.getBrandCustomData({brandId: brandId});
await AdminApi.apis.CampaignCustomData.getCampaignCustomData({campaignId: campaignId});
await AdminApi.apis.ProductCustomData.getProductCustomData({productIdentifier: productIdentifier});
await AdminApi.apis.ProductVariantCustomData.getProductVariantCustomData({variantIdentifier: variantIdentifier});
await AdminApi.apis.ShopCustomData.getShopCustomData({shopKey: shopKey});
await AdminApi.apis.ShopCategoriesCustomData.getShopCategoriesCustomData({shopKey: shopKey, shopCategoryId: shopCategoryId});
await AdminApi.apis.ShopCategoriesCountryCustomData.getShopCategoriesCountryCustomData({shopKey: shopKey, countryCode: countryCode, shopCategoryId: shopCategoryId});
await AdminApi.apis.ShopCountryCustomData.getShopCountryCustomData({shopKey: $shopKey, countryCode: countryCode});

Options

Parameter	Details
with	String Allows to load the following nested resources (supported only for `shopCategory` and `shopCategoryCountry` entities) within this request: inheritedCustomData

Whenever a user requests custom data for shopCategory or shopCategoryCountry specifying with=inheritedCustomData

If the custom data for the inherited property is not defined
- The custom data of the inherited property belonging to the first ancestor that explicitly defines the inherited properties will be returned.
Otherwise, the custom data of the inherited property for the current node will be returned and won’t be overridden/inherited.

Parameter	Details
isValid	Boolean A sample key for a boolean value of custom data
score	Integer A sample key for a integer value of custom data
name	String A sample key for a string value of custom data
localizedColor	Object A sample key for a string value scoped by locale
sampleJson	Object A sample key for a json value

Examples

await AdminApi.apis.BrandCustomData.getBrandCustomData({brandId: 5038});
await AdminApi.apis.CampaignCustomData.getCampaignCustomData({campaignId: 300});
await AdminApi.apis.ProductCustomData.getProductCustomData({productIdentifier: 1});
await AdminApi.apis.ProductVariantCustomData.getProductVariantCustomData({variantIdentifier: 1});
await AdminApi.apis.ShopCustomData.getShopCustomData({shopKey: 'ms'});
await AdminApi.apis.ShopCategoriesCustomData.getShopCategoriesCustomData({shopKey: 'ms', shopCategoryId: 112, with: 'inheritedCustomData'});
await AdminApi.apis.ShopCategoriesCountryCustomData.getShopCategoriesCountryCustomData({shopKey: 'ms', shopCategoryId: 112, countryCode: 'DE'});
await AdminApi.apis.ShopCountryCustomData.getShopCountryCustomData({shopKey: 'ms', countryCode: 'DE'});

Get Custom Data for a Specific Key

When retrieving custom data for a specific key, you must specify additional parameters defining the entity/record where you need to perform such operation.

This method is used to get custom data for a specific key.

await adminApi.apis.ShopCustomData.getShopCustomDataForKey({shopKey: shopKey, key: key});
await adminApi.apis.BrandCustomData.getBrandCustomDataForKey({brandId: brandId, key: key});
await adminApi.apis.ShopCategoriesCustomData.getShopCategoriesCustomDataForKey({shopKey: shopKey, shopCategoryId: shopCategoryId, key: key});
await adminApi.apis.ShopCategoriesCountryCustomData.getShopCategoriesCountryCustomDataForKey({shopKey: shopKey, shopCategoryId: shopCategoryId, countryCode: countryCode, key: key});
await adminApi.apis.ShopCountryCustomData.getShopCountryCustomDataForKey({shopKey: shopKey, countryCode: countryCode, key: key});
await adminApi.apis.ProductCustomData.getProductCustomDataForKey({productIdentifier: productIdentifier, key: key});
await adminApi.apis.ProductVariantCustomData.getProductVariantCustomDataForKey({variantIdentifier: variantIdentifier, key: key});
await adminApi.apis.CampaignCustomData.getCampaignCustomDataForKey({campaignId: campaignId, key: key});

Options

Parameter	Details
with	String Allows to load the following nested resources (supported only for `shopCategory` and `shopCategoryCountry` entities) within this request: inheritedCustomData

Whenever a user requests custom data for shopCategory or shopCategoryCountry specifying with=inheritedCustomData

If the custom data for the inherited property is not defined
The custom data of the inherited property belonging to the first ancestor that explicitly defines the inherited properties will be returned.
Otherwise, the custom data of the inherited property for the current node will be returned and won’t be overridden/inherited.

Get for a Specific Key

Get entity custom data for a specific key

await adminApi.apis.ShopCustomData.getShopCustomDataForKey({shopKey: 'ms', key: 'isValid'});
await adminApi.apis.BrandCustomData.getBrandCustomDataForKey({brandId: 5038, key: 'isValid'});
await adminApi.apis.ShopCategoriesCustomData.getShopCategoriesCustomDataForKey({shopKey: 'ms', shopCategoryId: 112, key: 'isValid', with: "inheritedCustomData"});
await adminApi.apis.ShopCategoriesCountryCustomData.getShopCategoriesCountryCustomDataForKey({shopKey: 'ms', shopCategoryId: 112, countryCode: 'DE', key: 'isValid'});
await adminApi.apis.ShopCountryCustomData.getShopCountryCustomDataForKey({shopKey: 'ms', countryCode: 'DE', key: 'isValid'});
await adminApi.apis.ProductCustomData.getProductCustomDataForKey({productIdentifier: 1, key: 'isValid'});
await adminApi.apis.ProductVariantCustomData.getProductVariantCustomDataForKey({variantIdentifier: 1, key: 'isValid'});
await adminApi.apis.CampaignCustomData.getCampaignCustomDataForKey({campaignId: 300, key: 'isValid'});

Delete Custom Data

When deleting custom data, you must specify additional parameters defining the entity/record where you need to perform such operation.

This method is used to delete custom data.

await AdminApi.apis.ShopCustomData.deleteShopCustomData({shopKey: shopKey});
await AdminApi.apis.BrandCustomData.deleteBrandCustomData({brandId: brandId});
await AdminApi.apis.ShopCategoriesCustomData.deleteShopCategoriesCustomData({shopKey: shopKey, shopCategoryId: shopCategoryId});
await AdminApi.apis.ShopCategoriesCountryCustomData.deleteShopCategoriesCountryCustomData({shopKey: shopKey, shopCategoryId: shopCategoryId, countryCode: countryCode});
await AdminApi.apis.ShopCountryCustomData.deleteShopCountryCustomData({shopKey: shopKey, countryCode: countryCode});
await AdminApi.apis.ProductCustomData.deleteProductCustomData({productIdentifier: productIdentifier});
await AdminApi.apis.ProductVariantCustomData.deleteProductVariantCustomData({variantIdentifier: variantIdentifier});
await AdminApi.apis.CampaignCustomData.deleteCampaignCustomData({campaignId: campaignId});

Examples

await AdminApi.apis.ShopCustomData.deleteShopCustomData({shopKey: 'ms'});
await AdminApi.apis.BrandCustomData.deleteBrandCustomData({brandId: 5038});
await AdminApi.apis.ShopCategoriesCustomData.deleteShopCategoriesCustomData({shopKey: 'ms', shopCategoryId: 112});
await AdminApi.apis.ShopCategoriesCountryCustomData.deleteShopCategoriesCountryCustomData({shopKey: 'ms', shopCategoryId: 112, countryCode: 'DE'});
await AdminApi.apis.ShopCountryCustomData.deleteShopCountryCustomData({shopKey: 'ms', countryCode: 'DE'});
await AdminApi.apis.ProductCustomData.deleteProductCustomData({productIdentifier: 1});
await AdminApi.apis.ProductVariantCustomData.deleteProductVariantCustomData({variantIdentifier: 1});
await AdminApi.apis.CampaignCustomData.deleteCampaignCustomData({campaignId: 300});

Delete Custom Data for a Specific Key

Learn how to delete custom data for a specific key.

When deleting custom data for a specific key, you must specify additional parameters defining the entity/record where you need to perform such operation.

About this Method This method is used to delete custom data for a specific key.

await AdminApi.apis.ShopCustomData.deleteShopCustomDataForKey({shopKey: shopKey, key: key});
await AdminApi.apis.BrandCustomData.deleteBrandCustomDataForKey({brandId: brandId, key: key});
await AdminApi.apis.ShopCategoriesCustomData.deleteShopCategoriesCustomDataForKey({shopKey: shopKey, shopCategoryId: shopCategoryId, key: key});
await AdminApi.apis.ShopCategoriesCountryCustomData.deleteShopCategoriesCountryCustomDataForKey({shopKey: shopKey, shopCategoryId: shopCategoryId, countryCode: countryCode, key: key});
await AdminApi.apis.ShopCountryCustomData.deleteShopCountryCustomDataForKey({shopKey: $shopKey, countryCode: countryCode, key: key});
await AdminApi.apis.ProductCustomData.deleteProductCustomDataForKey({productIdentifier: productIdentifier, key: key});
await AdminApi.apis.ProductVariantCustomData.deleteProductVariantCustomDataForKey({variantIdentifier: variantIdentifier, key: key});
await AdminApi.apis.CampaignCustomData.deleteCampaignCustomDataForKey({campaignId: campaignId, key: key});

Examples

Delete for a Specific Key Delete entity custom data for a specific key

await AdminApi.apis.ShopCustomData.deleteShopCustomDataForKey({shopKey: 'ms', key: 'isValid'});
await AdminApi.apis.BrandCustomData.deleteBrandCustomDataForKey({brandId: 5038, key: 'isValid'});
await AdminApi.apis.ShopCategoriesCustomData.deleteShopCategoriesCustomDataForKey({shopKey: 'ms', shopCategoryId: 112, key: 'isValid'});
await AdminApi.apis.ShopCategoriesCountryCustomData.deleteShopCategoriesCountryCustomDataForKey({shopKey: 'ms', shopCategoryId: 112, countryCode: 'DE', key: 'isValid'});
await AdminApi.apis.ShopCountryCustomData.deleteShopCountryCustomDataForKey({shopKey: 'ms', countryCode: 'DE', key: 'isValid'});
await AdminApi.apis.ProductCustomData.deleteProductCustomDataForKey({productIdentifier: 1, key: 'isValid'});
await AdminApi.apis.ProductVariantCustomData.deleteProductVariantCustomDataForKey({variantIdentifier: 1, key: 'isValid'});
await AdminApi.apis.CampaignCustomData.deleteCampaignCustomDataForKey({campaignId: 300, key: 'isValid'});

Create Custom Data Configuration

To create custom data for an entity, you need to specify the configuration for the custom data in the custom data configuration table.

When creating the custom data config with defaultValue given, it will be synced asynchronously to all the corresponding entities.

If there is no custom data assignment for the respective entity when creating the custom data configuration, then defaultValue is not mandatory in the create custom data configuration request.

Method Signature

await client.apis.CustomDataConfigs.create({entity: entity}, {requestBody: customDataConfig});

Create a custom data configuration

let customDataConfig = {
   properties: [
     {
        name: "test",
        type: "string",
        defaultValue: "default",
        inherit: false,
        isLocalized: false,
        rules: {
          "required": true
        }   
     }
   ]
};

await client.apis.CustomDataConfigs.create({entity: 'shop'}, {requestBody: customDataConfig});

Update Custom Data Configuration

When updating a custom data configuration, you always replace the existing values.

When updating the custom data config with defaultValue given, it will be synced asynchronously to all the corresponding entities.

If there is no custom data assignment for the respective entity when updating the custom data configuration, then defaultValue is not mandatory in the update custom data configuration request.

The syncing of the defaultValue is only applied to the very first defaultValue of the config i.e. updating the defaultValue multiple times won't change the already persisted defaultValue which is the first defaultValue provided or the value which is set manually by the user.

Method Signature

await client.apis.CustomDataConfigs.update({entity: entity}, {requestBody: customDataConfig});

As the syncing of the defaultValue to the corresponding entity is done asynchronously, there are some restrictions applied on updating the Custom Data Configurations in order to ensure the consistency of the data.

The following restrictions are only applied in case the corresponding entity has some existing custom data.

Updating the type property is prohibited.
Updating the minLength rule from lower value to higher value is prohibited.
Updating the maxLength rule from higher value to lower value is prohibited.
Updating the jsonSchema rule is prohibited.

Update a custom data configuration

let customDataConfig = {
   properties: [
     {
        name: "test",
        inherit: true,
        isLocalized: true,
        rules: {
          "required": true
        }   
     }
   ]
};

await client.apis.CustomDataConfigs.update({entity: 'shop'}, {requestBody: customDataConfig});

Get Custom Data Configuration

When retrieving a custom data configuration, you must specify the corresponding entity name of the custom data configuration.

Method Signature

await client.apis.CustomDataConfigs.get({entity: entity});

Get the custom data configuration for shop entity

await client.apis.CustomDataConfigs.get({entity: 'shop'});

Delete Custom Data Configuration

When deleting a custom data configuration, you must specify the corresponding entity name of the custom data configuration.

Deleting the custom data configuration for an entity will reset all the custom data for the corresponding entity asynchronously.

Method Signature

await client.apis.CustomDataConfigs.delete({entity: entity});

Delete the custom data configuration for shop entity

await client.apis.CustomDataConfigs.delete({entity: 'shop'});