docs
  1. SCAYLE Resource Center
  2. Developer Guides
  3. Products
  4. Manage Products Master Data

Manage Products Master Data

General

Master Categories provide the basis for setting up a flexible master data structure and efficiently managing product data in SCAYLE.

For each master category, one or more attribute groups can be assigned. The assigned attribute group can also be defined as mandatory to ensure that products (assigned to a master category) have all the required information. They define which attributes a product must have to go online and which attributes are differentiating. The product status Handling & Evaluation will be executed each time you make adjustments to master categories.

The primary purpose of master-level categories is to structure the product data. Therefore, they are not displayed in the shop front end.

Admin API

Master categories

Create master category

When creating master categories, you do not necessarily need to specify assigned attribute groups. However, superordinate categories inherit their attribute groups to subordinate ones.

This method is used to create a new master category.

let response = await adminApi.apis.masterCategories.createMasterCategory({requestBody: masterCategory});
let masterCategory = response.body;

When creating a new master category the following validation rules must pass:

  • All ancestors provided via path must exist.
  • A master category with the same path does not exist.
  • If attributes are provided, their group must exist.
  • A default value is only allowed for mandatory non-advanced attributes.

Parameters

ParameterTypeDescription
idintegerThe ID of the master category created by SCAYLE.
parentIdintegerThe ID of the parent master category if it exists.
pathstringThe complete category path.
attributesMasterCategoryAttributeList of attributes related to this category.

Create new root master category

let newMasterCategory = {
  path: [
    "NewCategory"
  ]
};

let response = await adminApi.apis.MasterCategories.createMasterCategory({}, {requestBody: newMasterCategory});
let createdMasterCategory = response.body;

Create new leaf master category

let newMasterCategory = {
    path: [
        "NewCategory",
        "NewLeafCategory"
    ]
};

let response = await adminApi.apis.MasterCategories.createMasterCategory({}, {requestBody: newMasterCategory});
let createdMasterCategory = response.body;

Create new master category with assigned attributes

let newMasterCategory = {
    path: [
        "NewCategory"
    ],
    attributes: [
        {
            name: "color",
            type: "simple",
            isMandatory: false
        }
    ]
};

let response = await adminApi.apis.MasterCategories.createMasterCategory({}, {requestBody: newMasterCategory});
let createdMasterCategory = response.body;

Complex creation of new master category

Create a new master category with mandatory attributes and default values

let newMasterCategory = {
    path: [
        "NewCategory"
    ],
    attributes: [
        {
            name: "color",
            type: "simple",
            isMandatory: false,
            defaultValue: 1
        }
    ]
};

let response = await adminApi.apis.MasterCategories.createMasterCategory({}, {requestBody: newMasterCategory});
let createdMasterCategory = response.body;

Update master category

If you update a master category, be aware that this might affect the products assigned to it and attributes inherited.

This method can be used to update an existing master category.

This method does not support partial updates.

let response = await adminApi.apis.MasterCategories.updateMasterCategory({masterCategoryId: masterCategoryId}, {requestBody: masterCategory});
let updatedMasterCategory = response.body;

When updating a master category the following validation rules must pass:

  • All ancestors provided via path must exist.
  • A master category with the same path does not exist, except for the provided category.
  • If attributes are provided, their group must exist.
  • A default value is only allowed for mandatory non-advanced attributes.

Updating master category mandatory attributes will trigger the status evaluation. The assigned products might end up in the problem status. As the status update is handled in the background, it might take some time until all effected products show up with their correct status.

Parameters

ParameterTypeDescription
idintegerThe ID of the master category created by SCAYLE.
parentIdintegerThe ID of the parent master category if it exists.
pathstringThe complete category path.
attributesMasterCategoryAttributeList of attributes related to this category.

Update Master Category Name

let response = await adminApi.apis.MasterCategories.getMasterCategory({
    masterCategoryId: 1
});

let masterCategory = response.body;

let index = masterCategory.path.length - 1;
masterCategory.path[index] = "NewName";

response = await adminApi.apis.MasterCategories.updateMasterCategory(
    { masterCategoryId: 1},
    {requestBody: masterCategory}
);

Move Master Category

All examples are assuming that the master category currently has a path Old > Fashion > Shirts and we want to move it to New > Shirts.

let response = await adminApi.apis.MasterCategories.getMasterCategory({
    masterCategoryId: 1
});

let masterCategory = response.body;

masterCategory.path = [
    "New",
    "Shirts"
];

response = await adminApi.apis.MasterCategories.updateMasterCategory(
    { masterCategoryId: 1},
    {requestBody: masterCategory}
);

Get master category

Get a single master category by ID

You can request a master category by using its ID. This method can be used to get an existing master category.

let response = await adminApi.apis.MasterCategories.getMasterCategory({
    masterCategoryId: 1
});

let masterCategory = response.body;

console.log(masterCategory);

Get a collection of master categories

When requesting multiple master categories, you can define how many results you wish to retrieve.

This method can be used to get a collection of existing master categories.

await adminApi.apis.MasterCategories.getMasterCategories({});

Options

ParameterTypeDescription
limitintegerMaximum number of items in the result. (default: 100, maximum: 1000)
filters[minId]integerMinimum master category ID of entities that should be returned.

Parameters

ParameterTypeDescription
entitiesMasterCategoryA collection of master categories.
cursorCursorAn object containing information for use in pagination.

Get a list of master categories

let response = await adminApi.apis.MasterCategories.getMasterCategories();
let masterCategories = response.body.entities;

masterCategories.forEach(
    masterCategory => console.log(masterCategory.path)
);

Delete master category

You can delete an existing master category at any time if the two following prerequisites apply:

  1. no products are assigned to category
  2. master category is a leaf category

This method can be used to delete an existing master category.

adminApi.apis.MasterCategories.deleteMasterCategory({masterCategoryId: masterCategoryId});

Parameters

ParameterTypeDescription
idintegerThe ID of the master category created by SCAYLE.
parentIdintegerThe ID of the parent master category if it exists.
pathstringThe complete category path.
attributesMasterCategoryAttributeList of attributes related to this category.

Update product master categories

This method can be used to update master categories for products.

When you update master categories, this will affect all products affiliated with it and may cause problem statuses.

This action will update the categories for all products of the same Master. By default, one master category is supported, but it can be changed to multiple ones on request during the integration.

let response = await adminApi.apis.MasterCategories.updateProductMasterCategories(
    {productIdentifier: productIdentifier},
    {requestBody: ProductMasterCategories}
);
let updatedCategories = response.body;

Options

The operation can be used with optional parameters - called options:

ParameterDetails
ignoreCategoryLocks

Boolean

Force an update of categories even if they might be locked.

See this example for details on how to use options.

When updating product master categories the following validation rules must pass:

  • The provided category paths must exist.

Updating product master categories will trigger the status evaluation for all products of the same master. Products might end up in the problem status.

Default Attributes

If the new master categories have default attributes assigned, these are automatically added to all products/images/variants of the same master, if these do not already have an attribute of the same group assigned.

Locks

To avoid accidentally updating categories that were manually changed in the SCAYLE, the query parameter ignoreCategoryLocks can be used to control the behaviour of how these updates should be handled.

The default behaviour is to respect category locks. This will prevent category updates. If you want to force updates of categories, you need to set ignoreCategoryLocks = true. In this case, all categories for all products of the same master get updated even if they are locked.

Update Product Master Categories

let categories = {
    paths: [
        [
            "Fashion",
            "Women",
            "Shirts"
        ]
    ]
}

let response = await adminApi.apis.MasterCategories.updateProductMasterCategories(
    {productIdentifier: 1},
    {requestBody: categories}
);

let updatedCategories = response.body;

Update product master categories ignoring locks

let categories = {
    paths: [
        [
            "Fashion",
            "Women",
            "Shirts"
        ]
    ]
}

let response = await adminApi.apis.MasterCategories.updateProductMasterCategories(
    {
        productIdentifier: 1,
        ignoreCategoryLocks: true
    },
    {requestBody: categories}
);

let updatedCategories = response.body;

Update the master categories of product master

This method can be used to update master categories for a product master and its products.

When updating a master category, all products belonging to the same master will reflect the changes, and the status evaluation is triggered.

Updating a master category will trigger the status evaluation for all products of the same product master. The products might end up in the problem status.

let response = await adminApi.apis.Masters.updateProductMasterMasterCategories(
    {productIdentifier: productMasterIdentifier},
    {requestBody: ProductMasterCategories}
);
let updatedCategories = response.body;

Options

The operation can be used with optional parameters - called options:

ParameterDetails
ignoreCategoryLocks

Boolean

Force an update of categories even if they might be locked.

See this example for details on how to use options.

When updating product-master master categories the following validation rules must pass:

  • The provided category paths must exist.

Default Attributes

If the new master categories have default attributes assigned, these are automatically added to all products/images/variants of the same master, if these do not already have an attribute of the same group assigned.

Locks

To avoid accidentally updating categories that were manually changed in SCAYLE, the query parameter ignoreCategoryLocks can be used to control the behaviour of how these updates should be handled.

The default behaviour is to respect category locks. This will prevent category updates. If you want to force updates of categories, you need to set ignoreCategoryLocks=true. In this case, all categories for all products of the given master get updated even if they are locked.

Update ProductMaster Master Categories

let categories = {
    paths: [
        [
            "Fashion",
            "Women",
            "Shirts"
        ]
    ]
}

let response = await adminApi.apis.Masters.updateProductMasterMasterCategories(
    {productMasterIdentifier: "masterReferenceKey"},
    {requestBody: categories}
);

let updatedCategories = response.body;

Update product master categories ignoring locks

let categories = {
    paths: [
        [
            "Fashion",
            "Women",
            "Shirts"
        ]
    ]
}

let response = await adminApi.apis.Masters.updateProductMasterMasterCategories(
    {
        productIdentifier: "masterReferenceKey",
        ignoreCategoryLocks: true
    },
    {requestBody: categories}
);

let updatedCategories = response.body;

Product master attributes

Product master attributes can be used to enhance product data displayed in a shop, for example, product material, color and more.

Shop Overrides

Attributes can be either shop-country-specific or global. When an attribute is shop-country-specific, it means that an attribute value will be applied for the specified shop country. This makes it easy to customize attributes in relation to a specific shop country while still maintaining a sensible default value for all other shop countries using the same attribute.

Attribute Locks

To avoid accidentally deleting or updating attributes that were manually added or edited via the SCAYLE Panel, the query parameter ignoreAttributeLocks can be used to control the behavior of how these updates should be handled.

The default behaviour is to respect attribute locks. Thus, even if an attribute is present in the payload, it will not be updated. The same behaviour will be applied, if an attribute is omitted in the payload, so it will not get deleted.

If you want to force updates or deletion of attributes, you need to set ignoreAttributeLocks = true. In this case, all attributes get updated or deleted even if they are locked.

Handling missing advanced attributes

If you encounter any missing advanced attribute on one of the entities, please refer to the respective endpoint fetching a single attribute. For product master attributes this will be the endpoint GetProductMasterAttribute. This endpoint will provide you with information why the advanced attribute is missing, i.e. it will return an error message with the reason.

Get a collection of product master attributes

SCAYLE allows you to retrieve all attributes attached to a product master.

The method is used to get a collection of existing product master attributes.

let response = await adminApi.apis.Masters.allAttributes({ productMasterIdentifier: productMasterIdentifier });
let productMasterAttributeCollection = response.body.entities;

Get a list of Product Master Attributes

let response = await adminApi.apis.Masters.allAttributes({ productMasterIdentifier: 1 });
let productMasterAttributes = response.body.entities;

Get a product master attribute

In SCAYLE, you can request a product master's attribute of the given group.

The method is used to get an existing product master attribute.

let response = await adminApi.apis.Masters.getProductMasterAttribute({
    productMasterIdentifier: productMasterIdentifier,
    attributeGroupName: attributeGroupName
});

let productMasterAttribute = response.body;

Example

let response = await adminApi.apis.Masters.getProductMasterAttribute({
    productMasterIdentifier: 1,
    attributeGroupName: "material"
});

let productMasterAttribute = response.body;

Create or update a product master attribute

In SCAYLE, you can create a product master attribute and override its value for a specific shop.

The method is used to create a product master attribute if it does not exist or update an existing product master attribute.

If shop-country-specific values are not provided, then the existing shop country overrides will not be modified. Otherwise, shop country overrides will be replaced with the provided values. In case you wish to remove shop country specific values for a certain attribute, you have to explicitly set shopCountrySpecific to an empty Array (PHP & JavaScript) ArrayList (Java) (see update locked attributes example).

Attributes of system attribute group category may not be created or updated.

const response = await adminApi.apis.Attributes.updateOrCreateProductMasterAttribute(
    {productMasterIdentifier: productMasterIdentifier},
    {requestBody: productMasterAttribute}
);

const createdProductMasterAttribute = response.body;

Options

Product master attributes write operations can be used with optional parameters - called options:

ParameterDetails
ignoreAttributeLocks

Boolean

Force an update of attributes even if they are locked.

Updating or creating a product master attribute will trigger the status evaluation for all products belonging to the same master. Some products might end up in the problem status.

Create a simple product master attribute

const attribute = {
    "name": "size",
    "type": "simple",
    "value": "M"
};

const response = await adminApi.apis.Attributes.updateOrCreateProductMasterAttribute(
    {productMasterIdentifier: 1},
    {requestBody: attribute}
);

const createdAttribute = response.body;

Create a simple list product master attribute

const attribute = {
    "name": "season",
    "type": "simpleList",
    "value": ["autumn", "winter"]
};

const response = await adminApi.apis.Attributes.updateOrCreateProductMasterAttribute(
    {productMasterIdentifier: 1},
    {requestBody: attribute}
);

const createdAttribute = response.body;

Create a localized list product master attribute

const attribute = {
    "name": "color",
    "type": "localizedStringList",
    "value": [
        {"de_DE": "weiß", "en_GB": "white"},
        {"de_DE": "schwarz", "en_GB": "black"}
    ]
};

const response = await adminApi.apis.Attributes.updateOrCreateProductMasterAttribute(
    {productMasterIdentifier: 1},
    {requestBody: attribute}
);

const createdAttribute = response.body;

Create an advanced product master attribute

const attribute = {
    "name": "dimensions",
    "type": "advanced",
    "value": {
        "height": 100,
        "width": 30,
        "unit": "cm"
    }
};

const response = await adminApi.apis.Attributes.updateOrCreateProductMasterAttribute(
    {productMasterIdentifier: 1},
    {requestBody: attribute}
);

const createdAttribute = response.body;

Create an advanced list product master attribute

const attribute = {
    "name": "material",
    "type": "advancedList",
    "value": [
        {
            "name": "wool",
            "percentage": 80
        },
        {
            "name": "cotton",
            "percentage": 20
        }
    ]   
};

const response = await adminApi.apis.Attributes.updateOrCreateProductMasterAttribute(
    {productMasterIdentifier: 1},
    {requestBody: attribute}
);

const createdAttribute = response.body;

Update a simple attribute ignoring locks

const productMasterAttribute = {
    "name": "material",
    "type": "simple",
    "value": "cotton"
};

const response = await adminApi.apis.Attributes.updateOrCreateProductMasterAttribute(
    {productMasterIdentifier: 1, ignoreAttributeLocks: true},
    {requestBody: productMasterAttribute}
);

const updatedProductMasterAttribute = response.body;

Create or update simple product master attributes

Override attribute value for certain shop country.

const shopCountrySpecificAttribute = {
    "shopKey": "ms",
    "countryCode": "de",
    "value": "polyester"
};

const productMasterAttribute = {
    "name": "material",
    "type": "simple",
    "value": "cotton",
    "shopCountrySpecific": [
        shopCountrySpecificAttribute
    ]
};

const response = await adminApi.apis.Attributes.updateOrCreateProductMasterAttribute(
    {productMasterIdentifier: 1}, 
    {requestBody: productMasterAttribute}
);

const updatedProductMasterAttribute = response.body;

Update locked simple product master attributes

Update locked simple product master attributes un-assign existing product master attributes with an empty array / ArrayList.

const productMasterAttribute = {
    "name": "material",
    "type": "simple",
    "value": "cotton",
    "shopCountrySpecific": []
};

const response = await adminApi.apis.Attributes.updateOrCreateProductMasterAttribute(
    {productMasterIdentifier: 1, ignoreAttributeLocks: true},
    {requestBody: productMasterAttribute}
);

const updatedProductMasterAttribute = response.body;

Delete a product master attribute

Product master attributes are deleted along with the shop overrides.

Attributes of system attribute group category may not be deleted.

The method is used to delete a product master attribute.

adminApi.apis.Attributes.deleteProductMasterAttribute({
    productMasterIdentifier: productMasterIdentifier,
    attributeGroupName: attributeGroupName
});

Options

The operation can be used with optional parameters - called options:

ParameterDetails
ignoreAttributeLocks

Boolean

Force attributes deletion even if they are locked.

Deleting a product master attribute will trigger the status evaluation. The product might end up in the problem status.

Delete a Product Master Attribute

adminApi.apis.Attributes.deleteProductMasterAttribute({
  productIdentifier: 1,
  attributeGroupName: "material"
});

Delete a product master attribute ignoring locks

adminApi.apis.Attributes.deleteProductMasterAttribute({
  productMasterIdentifier: 1,
  attributeGroupName: "material",
  ignoreAttributeLocks: true
});
Previous
Manage Media / Assets
Next up
Using Products in your Store