Product specifications
Learn how to create, update, and delete product specifications using the VTEX API.
Learn more with this article about specifications.
If you wish to implement color variation in your products, we recommend you don't use specifications. Instead, see this tutorial about How to implement product color variation.
Data Model
| Field | Description | Required | Format | Default |
|---|---|---|---|---|
Id | ID of Specification. This Id is used to delete/update the specification | No | Integer | AutoIncrement |
ProductId | ID of Product | Yes | Integer | - |
FieldId | Field ID | Yes | Integer | - |
FieldValueId | ID of FieldValue. ONLY for FieldTypeId(5,6,7). | Mandatory for 5,6,7. Must not be used for any other field types. | Integer | null |
Text | Value of specification. Only for FieldTypeId different from (5,6,7) | Mandatory for all fields except 5,6,7 where it must not be used. | String | null |
Implementation
To create a product specification, use the API below. You must have previously saved the ID of the field for which you want to create a specification.
If the specification field is of the Combo, Radio or Checkbox type (
FieldTypeIdof 5, 6 and 7 respectively), theFieldValueIdfield is required and theTextfield is not. For text type fields, it is not necessary to create values for the field; that is, theFieldValueIdattribute must benulland theTextattribute must be provided with the specification value.
Create Specification - Example #1 (text field)
POST
_10https://{{accountName}}.vtexcommercestable.com.br/api/catalog/pvt/product/{{productId}}/specification
Body:
_10{_10 "FieldId": 21,_10 "Text": "This is a test for specification field type text",_10}
Header:
_10Accept: application/json _10Content-Type: application/json _10X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}} _10X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}
Response:
_10Status: 200 OK
_10{_10 "Id": 39,_10 "ProductId": 42,_10 "FieldId": 21,_10 "FieldValueId": null,_10 "Text": "This is a test for specification field type text"_10}
Create Specification - Example #2 (Non-text field)
POST
_10https://{{accountName}}.vtexcommercestable.com.br/api/catalog/pvt/product/{{productId}}/specification
Body:
_10{_10 "FieldId": 22,_10 "FieldValueId": 65,_10}
Headers:
_10Accept: application/json _10Content-Type: application/json _10X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}} _10X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}
Response:
_10Status: 200 OK
_10{_10 "Id": 38,_10 "ProductId": 42,_10 "FieldId": 22,_10 "FieldValueId": 65,_10 "Text": "Metal"_10}
Get all specifications from a product
To get all specification fields and values from a product, use the Get product specifications and their information by product ID endpoint. See an example response below:
_16[_16 {_16 "Id": 38,_16 "ProductId": 42,_16 "FieldId": 22,_16 "FieldValueId": 65,_16 "Text": "Metal"_16 },_16 {_16 "Id": 39,_16 "ProductId": 42,_16 "FieldId": 21,_16 "FieldValueId": null,_16 "Text": "This is a test for specification field type text"_16 }_16]
Update product specification
To update a product specification, use the Update a product specification by product ID endpoint. It is also possible to update specification values in bulk.
Example request
Body:
_14[_14 {_14 "value": [_14 "Metal"_14 ],_14 "Id": 22_14 },_14 {_14 "value": [_14 "This is the second test for specification field type text"_14 ],_14 "Id": 21_14 }_14]
Response:
_10Status: 200 OK
Remove product specifications
To remove a specification from a product, use the Delete product specification endpoint.
Remove all specifications from a product
To delete all specifications registered in a product, use the Delete all product specification endpoint.