Documentation
Feedback
Guides

Integration Guides
Catalog
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

FieldDescriptionRequiredFormatDefault
NameGroup's NameYesString (150)-
CategoryIdCategory where this group is associatedNoIntegernull
PositionStore Framework - Deprecated. Classic CMS -NoIntegernull

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.

TypeID
Text1
Long Text (Textarea)2
Number4
Dropdown5
Radio6
CheckBox7
Indexed Text8
Long Indexed Text9

️ 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 Adding product specifications or fields or the Adding SKU specifications or fields documentation.

Specification data model

FieldDescriptionRequiredFormatDefault
FieldTypeIdSpecification Field Type Id (FieldType Table).YesInteger-
CategoryIdCategoryId associated with this field.NoIntegernull
FieldGroupIdGroupId associated with this field.YesInteger-
NameField name.YesString (150)null
DescriptionDeprecated.NoStringnull
PositionStore 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.NoInteger0
IsFilterStore Framework - Deprecated. Classic CMS - To allow the specification field to be used as a facet (filter) on the search navigation bar.NoBoolean (true/false)false
IsRequiredTo make the specification field required.NoBoolean (true/false)false
IsOnProductDetailsStore Framework - Deprecated. Classic CMS -If field is visible on the Product page.NoBoolean (true/false)false
IsStockKeepingUnitIf true, it will be added as a SKU specification field. If false, it will be added as a product specification field.NoBoolean (true/false)false
IsWizardDeprecated.NoBoolean (true/false)false
IsActiveEnable/Disable field.NoBoolean (true/false)false
IsTopMenuLinkActiveStore Framework - Deprecated. Classic CMS - To make the specification field visible in the store's upper menu.NoBoolean (true/false)false
IsSideMenuLinkActiveStore Framework - Deprecated. Classic CMS - To make the specification field clickable in the search navigation barNoBoolean (true/false)false
DefaultValueSpecification default value.NoStringnull

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:

{"base64":"  ","img":{"width":1008,"height":1056,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":119122,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/specifications-0.png"}}

Specification values data model

FieldDescriptionRequiredFormatDefault
FieldIdFieldId associated with this fieldvalueYesInteger-
NameName of field valueYesString (150)-
TextDeprecatedNoStringnull
IsActiveEnable/Disable field valueNoBoolean (true/false)false
PositionThe position of the value to be shown on product registration page (/admin/Site/Produto.aspx)NoInteger0

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.

Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
On this page