Specifications

Specifications are additional properties that can be added to your store's products or SKUs. A specification is used to create site browsing filters and to differentiate SKUs and products within the product page.

Here we take a look at some of the integration aspects of specifications, but we recommend you also check this detailed step by step guide on How to create a specification.

Groups

To create specifications, it is necessary to register the groups. Groups are specification groupers, for example, we can create a group named Technical Specifications, and in it we can insert specifications referring to the product's technical data, such as material, voltage, dimensions, etc.

🚧

The groups and fields created will be valid for its registration category and for all child categories. For example, if a field is created in the root category, it will be available in all store categories.

Usually just one group is created at root level and all the specification fields are associated with this group.

Groups data model

Field Description Required Format Default
Name Group's Name Yes String (150) -
CategoryId Category where this group is associated No Integer null
Position Store Framework - Deprecated

Classic CMS -

No Integer null

API integration

The Create specification group API request may be used to create your groups.

🚧

If the CategoryId field is null, the group will be created in the root category.

Example request

Body:

{
    "CategoryId": null,
    "Name": "Technical Specifications",
    "Position": 1
}

Response:

{
    "Id": 34,
    "CategoryId": null,
    "Name": "Technical Specifications",
    "Position": 1
}

Specification fields

Specifications are additional properties that can be added to your store's products or SKUs. In VTEX, these specifications are associated with specific categories.

Product Specification

A product specification is generally used to create site browsing filters or to display additional product information.

For example, in a fashion store you would be able to create a product specification to let your client know which type of fabric is sold in your store.

This information could be displayed as a filter in the search navigation menu or as an informative text inside the product page.

Product specifications can receive data such as strings and numbers, which VTEX APIs then consume and use for front-end customizations or to send information to external integrations.

SKU Specifications

SKU specifications are used to create site browsing filters and to differentiate SKUs within the product page.

For example, a store that sells shirts, you would be able to create a SKU specification to tell your products apart by size.

Your SKU specifications would have values such as XS, S, M, L and XL. These would be used as a browsing filter on your site. In addition, these specifications would work as SKU selectors on the product page.

🚧

In VTEX, SKU specifications are mandatory fields required to add SKUs, meaning that if a specification were to be created in a category, all SKUs within that category would need to carry this new specification. All these SKUs are therefore disabled until this new specification is added to the SKUs of the category in question.

FieldType

When registering fields, it is necessary to specify the type of values accepted by that field. Available options are listed below with their respective IDs.

Fields as dropdown, radio or checkbox can be used as filters on the search navigation menu.

Type ID
Text 1
Long Text (Textarea) 2
Number 4
Dropdown 5
Radio 6
CheckBox 7
Indexed Text 8
Long Indexed Text 9

🚧

For SKU fields (IsStockKeepingUnit = true) the only types of fields available are Dropdown and Radio, IDs 5 and 6 respectively.

For more details about each field, you can access the Setting up the specification type documentation.

Specification data model

Field Description Required Format Default
FieldTypeId Specification Field Type Id (FieldType Table) Yes Integer -
CategoryId CategoryId associated with this field No Integer null
FieldGroupId GroupId associated with this field Yes Integer -
Name Field name Yes String (150) null
Description Deprecated No String null
Position Store Framework - Deprecated

Classic CMS - This position number is used in ordering the fields both in the navigation menu and in the field listing on the product page

No Integer 0
IsFilter Store Framework - Deprecated

Classic CMS - To allow the specification field to be used as a facet (filter) on the search navigation bar.

No Boolean (true/false) false
IsRequired To make the specification field required No Boolean (true/false) false
IsOnProductDetails Store Framework - Deprecated

Classic CMS -If field is visible on the Product page

No Boolean (true/false) false
IsStockKeepingUnit If true, it will be added as a SKU specification field. If false, it will be added as a product specification field. No Boolean (true/false) false
IsWizard Deprecated No Boolean (true/false) false
IsActive Enable/Disable field No Boolean (true/false) false
IsTopMenuLinkActive Store Framework - Deprecated

Classic CMS - To make the specification field visible in the store's upper menu

No Boolean (true/false) false
IsSideMenuLinkActive Store Framework - Deprecated

Classic CMS - To make the specification field clickable in the search navigation bar

No Boolean (true/false) false
DefaultValue No String null

API integration

To create a specification, use the Create specification API endpoint. See the example request below.

Body:

{
    "FieldTypeId": 6,
    "CategoryId": 2000089,
    "FieldGroupId": 34,
    "Name": "Material",
    "Position": 1,
    "IsFilter": false,
    "IsRequired": true,
    "IsOnProductDetails": false,
    "IsStockKeepingUnit": false,
    "IsActive": true,
    "IsTopMenuLinkActive": false,
    "IsSideMenuLinkActive": true,
    "DefaultValue": ""
}

🚧

If the CategoryId field is null, the field will be created in the root category.

Response:

{
    "Id": 193,
    "FieldTypeId": 6,
    "CategoryId": 2000089,
    "FieldGroupId": 34,
    "Name": "Material",
    "Description": null,
    "Position": 1,
    "IsFilter": true,
    "IsRequired": true,
    "IsOnProductDetails": false,
    "IsStockKeepingUnit": false,
    "IsWizard": false,
    "IsActive": true,
    "IsTopMenuLinkActive": false,
    "IsSideMenuLinkActive": false,
    "DefaultValue": null
}

Specification values

After creating the specification fields, if the FieldTypeId is 5, 6 or 7 (Combo, Radio or Checkbox), it is necessary to register the respective possible values.

Those values will be shown on product register page like this one:

Product register page example with specificationProduct register page example with specification

Product register page example with specification

Specification values data model

Field Description Required Format Default
FieldId FieldId associated with this fieldvalue Yes Integer -
Name Name of field value Yes String (150) -
Text Deprecated No String null
IsActive Enable/Disable field value No Boolean (true/false) false
Position The position of the value to be shown on product registration page (/admin/Site/Produto.aspx) No Integer 0

API integration

To register a new value for a specification use the Create specifications value API endpoint.

🚧

Use this request for one value of one specification at a time. To register multiple values to one specification, you will need to create a request for each of the values.

See the example request below.

Body:

{
    "FieldId": 193,
    "Name": "Metal",
    "IsActive": true,
    "Position": 1
}

Response:

{
    "FieldValueId": 360,
    "FieldId": 193,
    "Name": "Metal",
    "Text": null,
    "IsActive": true,
    "Position": 1
}

❗️

You should activate specification fields, otherwise they will not work.


Did this page help you?