Documentation
Feedback
Guides

Managing products

Learn how to create and update a product with the Catalog API.

This step-by-step guide will walk you through the process of creating and updating a product within the VTEX platform.

A product is a generic definition of an item that is part of your store’s Catalog, for instance, a shirt.

Products may vary by model, color, size, among other characteristics. Therefore, it would be possible to have the same product (shirt) in different models, like short or long sleeves, gray or pink color, sizes S, M or L.

Each variation, such as a long sleeve gray size S shirt, will correspond to a Stock Keeping Unit (SKU), which is the actual item in the inventory that customers can purchase. Before creating SKUs, you must create a product.

Before you begin

Before you begin managing your SKUs, make sure you've completed the following steps:

  • Obtain API Credentials: Ensure you have a valid appKey and appToken with the necessary permissions to access the Catalog API. For more information, please refer to the Roles article.

Creating a product

When creating or updating products, the product must be associated with their corresponding brand and most specific category. Hence, use the Create product with category and brand endpoint to insert a new product, considering the following scenarios:

Regardless of the type of request, if there is a need to create a new product with a specific custom product ID, it is possible to specify the Id (integer) in the request body. Otherwise, VTEX will generate the ID automatically.

We recommend leaving VTEX to automatically generate an ID, by not including a custom product ID in the Id field of the request body. The generated ID can be retrieved in the request's response and must be stored in the system for future updates of this product.

Click the steps below to navigate through this article and explore specific topics. Relevant code will be highlighted and focused for your convenience. Additionally, in the code viewer on the right, you can switch between different code files or tabs to view the corresponding code examples.

Type 1 - New product, category, and brand

Create a new product as well as a new category path (including subcategories) and a new brand by specifying the CategoryPath and BrandName parameters in the Create product with category and brand endpoint request body.

Shell
Python
Node.js

_10
curl --request post \
_10
--url https://{accountName}.vtexcommercestable.com.br/api/catalog/pvt/product \
_10
--header 'Accept: application/json' \
_10
--header 'Content-Type: application/json' \
_10
--header 'X-VTEX-API-AppKey: {appKey}' \
_10
--header 'X-VTEX-API-AppToken: {appToken}' \
_10
--data '{body}'

Request
Response

_16
{
_16
"Name": "Black T-Shirt",
_16
"CategoryPath": "Mens/Clothing/T-Shirts",
_16
"BrandName": "Nike",
_16
"RefId": "31011706925",
_16
"Title": "Black T-Shirt",
_16
"LinkId": "tshirt-black",
_16
"Description": "This is a cool Tshirt",
_16
"ReleaseDate": "2022-01-01T00:00:00",
_16
"IsVisible": true,
_16
"IsActive": true,
_16
"TaxCode": "",
_16
"MetaTagDescription": "tshirt black",
_16
"ShowWithoutStock": true,
_16
"Score": 1
_16
}

Type 1 with custom Id

If there is a need to create a new product with a specific custom product ID, specify the Id (integer) in the request body.

Shell
Python
Node.js

_10
curl --request post \
_10
--url https://{accountName}.vtexcommercestable.com.br/api/catalog/pvt/product \
_10
--header 'Accept: application/json' \
_10
--header 'Content-Type: application/json' \
_10
--header 'X-VTEX-API-AppKey: {appKey}' \
_10
--header 'X-VTEX-API-AppToken: {appToken}' \
_10
--data '{body}'

Request
Response

_17
{
_17
"Id": 42,
_17
"Name": "Zoom Stefan Janoski Canvas RM SB Varsity Red",
_17
"CategoryPath": "Mens/Clothing/T-Shirts",
_17
"BrandName": "Nike",
_17
"RefId": "sr_1_90",
_17
"Title": "Zoom Stefan Janoski Canvas RM SB Varsity Red",
_17
"LinkId": "stefan-janoski-canvas-varsity-red",
_17
"Description": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",
_17
"ReleaseDate": "2023-01-01T00:00:00",
_17
"IsVisible": true,
_17
"IsActive": true,
_17
"TaxCode": "",
_17
"MetaTagDescription": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",
_17
"ShowWithoutStock": true,
_17
"Score": 1
_17
}

Type 2 - New product, existing category and brand

Creating a new product given an existing CategoryId and an existing BrandId by specifying the CategoryId and BrandId parameters in the Create product with category and brand endpoint request body.

Shell
Python
Node.js

_10
curl --request post \
_10
--url https://{accountName}.vtexcommercestable.com.br/api/catalog/pvt/product \
_10
--header 'Accept: application/json' \
_10
--header 'Content-Type: application/json' \
_10
--header 'X-VTEX-API-AppKey: {appKey}' \
_10
--header 'X-VTEX-API-AppToken: {appToken}' \
_10
--data '{body}'

Request
Response

_17
{
_17
"Name": "Zoom Stefan Janoski Canvas RM SB Varsity Red",
_17
"DepartmentId": 2000089,
_17
"CategoryId": 2000090,
_17
"BrandId": 12121219,
_17
"LinkId": "stefan-janoski-canvas-varsity-red",
_17
"RefId": "sr_1_90",
_17
"IsVisible": true,
_17
"Description": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",
_17
"DescriptionShort": "The Nike Zoom Stefan Janoski is made with a premium leather.",
_17
"ReleaseDate": "2023-01-01T00:00:00",
_17
"KeyWords": "Zoom,Stefan,Janoski",
_17
"Title": "Zoom Stefan Janoski Canvas RM SB Varsity Red",
_17
"IsActive": true,
_17
"MetaTagDescription": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",
_17
"ShowWithoutStock": true,
_17
}

Type 2 with custom Id

If there is a need to create a new product with a specific custom product ID, specify the Id (integer) in the request body.

Shell
Python
Node.js

_10
curl --request post \
_10
--url https://{accountName}.vtexcommercestable.com.br/api/catalog/pvt/product \
_10
--header 'Accept: application/json' \
_10
--header 'Content-Type: application/json' \
_10
--header 'X-VTEX-API-AppKey: {appKey}' \
_10
--header 'X-VTEX-API-AppToken: {appToken}' \
_10
--data '{body}'

Request
Response

_18
{
_18
"Id": 42,
_18
"Name": "Zoom Stefan Janoski Canvas RM SB Varsity Red",
_18
"DepartmentId": 2000089,
_18
"CategoryId": 2000090,
_18
"BrandId": 12121219,
_18
"LinkId": "stefan-janoski-canvas-varsity-red",
_18
"RefId": "sr_1_90",
_18
"IsVisible": true,
_18
"Description": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",
_18
"DescriptionShort": "The Nike Zoom Stefan Janoski is made with a premium leather.",
_18
"ReleaseDate": "2023-01-01T00:00:00",
_18
"KeyWords": "Zoom,Stefan,Janoski",
_18
"Title": "Zoom Stefan Janoski Canvas RM SB Varsity Red",
_18
"IsActive": true,
_18
"MetaTagDescription": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",
_18
"ShowWithoutStock": true,
_18
}

Retrieving product data

You can retrieve product information by calling the Get product by ID endpoint.

Make sure to copy the response body, modify specific fields and use the full updated body as a request when updating a product.

Shell
Python
Node.js

_10
curl --request get \
_10
--url 'https://{accountName}.vtexcommercestable.com.br/api/catalog/pvt/product/{productId}' \
_10
--header 'Accept: application/json' \
_10
--header 'Content-Type: application/json' \
_10
--header 'X-VTEX-API-AppKey: {appKey}' \
_10
--header 'X-VTEX-API-AppToken: {appToken}' \

Request
Response

_23
{
_23
"Id": 42,
_23
"Name": "Zoom Stefan Janoski Canvas RM SB Varsity Red",
_23
"DepartmentId": 2000089,
_23
"CategoryId": 2000090,
_23
"BrandId": 12121219,
_23
"LinkId": "stefan-janoski-canvas-varsity-red",
_23
"RefId": "sr_1_90",
_23
"IsVisible": true,
_23
"Description": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",
_23
"DescriptionShort": "The Nike Zoom Stefan Janoski is made with a premium leather.",
_23
"ReleaseDate": "2023-01-01T00:00:00",
_23
"KeyWords": "Zoom,Stefan,Janoski",
_23
"Title": "Zoom Stefan Janoski Canvas RM SB Varsity Red",
_23
"IsActive": true,
_23
"TaxCode": "",
_23
"MetaTagDescription": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",
_23
"SupplierId": 1,
_23
"ShowWithoutStock": true,
_23
"AdWordsRemarketingCode": null,
_23
"LomadeeCampaignCode": null,
_23
"Score": 1
_23
}

Updating a product

If you need to change any product field, it is necessary to send all the other fields in the request. Otherwise, all other previously configured information will be deleted. Therefore, before making a change, you should get the product data for the same Id and use the response as a template to make the change.

If you want to update information from an existing product, send a request to the Update product endpoint, indicating the Id of the existing product.

Shell
Python
Node.js

_10
curl --request put \
_10
--url 'https://{accountName}.vtexcommercestable.com.br/api/catalog/pvt/product/{productId}' \
_10
--header 'Accept: application/json' \
_10
--header 'Content-Type: application/json' \
_10
--header 'X-VTEX-API-AppKey: {appKey}' \
_10
--header 'X-VTEX-API-AppToken: {appToken}' \
_10
--data '{body}'

Request
Response

_23
{
_23
"Id": 42,
_23
"Name": "Zoom Stefan Janoski Canvas RM SB Varsity Red",
_23
"DepartmentId": 2000089,
_23
"CategoryId": 2000090,
_23
"BrandId": 12121219,
_23
"LinkId": "stefan-janoski-canvas-varsity-red",
_23
"RefId": "sr_1_90",
_23
"IsVisible": true,
_23
"Description": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",
_23
"DescriptionShort": "The Nike Zoom Stefan Janoski is made with a premium leather.",
_23
"ReleaseDate": "2023-01-01T00:00:00",
_23
"KeyWords": "Zoom,Stefan,Janoski",
_23
"Title": "Zoom Stefan Janoski Canvas RM SB Varsity Re",
_23
"IsActive": true,
_23
"TaxCode": "",
_23
"MetaTagDescription": "The Nike Zoom Stefan Janoski Men's Shoe is made with a premium leather upper for superior durability and a flexible midsole for all-day comfort. A tacky gum rubber outsole delivers outstanding traction.",
_23
"SupplierId": 1,
_23
"ShowWithoutStock": true,
_23
"AdWordsRemarketingCode": null,
_23
"LomadeeCampaignCode": null,
_23
"Score": 1
_23
}

Type 1 - New product, category, and brand

Create a new product as well as a new category path (including subcategories) and a new brand by specifying the CategoryPath and BrandName parameters in the Create product with category and brand endpoint request body.

Type 1 with custom Id

If there is a need to create a new product with a specific custom product ID, specify the Id (integer) in the request body.

Type 2 - New product, existing category and brand

Creating a new product given an existing CategoryId and an existing BrandId by specifying the CategoryId and BrandId parameters in the Create product with category and brand endpoint request body.

Type 2 with custom Id

If there is a need to create a new product with a specific custom product ID, specify the Id (integer) in the request body.

Retrieving product data

You can retrieve product information by calling the Get product by ID endpoint.

Make sure to copy the response body, modify specific fields and use the full updated body as a request when updating a product.

Updating a product

If you need to change any product field, it is necessary to send all the other fields in the request. Otherwise, all other previously configured information will be deleted. Therefore, before making a change, you should get the product data for the same Id and use the response as a template to make the change.

If you want to update information from an existing product, send a request to the Update product endpoint, indicating the Id of the existing product.

Shell
Python
Node.js

_10
curl --request post \
_10
--url https://{accountName}.vtexcommercestable.com.br/api/catalog/pvt/product \
_10
--header 'Accept: application/json' \
_10
--header 'Content-Type: application/json' \
_10
--header 'X-VTEX-API-AppKey: {appKey}' \
_10
--header 'X-VTEX-API-AppToken: {appToken}' \
_10
--data '{body}'

Request
Response

_16
{
_16
"Name": "Black T-Shirt",
_16
"CategoryPath": "Mens/Clothing/T-Shirts",
_16
"BrandName": "Nike",
_16
"RefId": "31011706925",
_16
"Title": "Black T-Shirt",
_16
"LinkId": "tshirt-black",
_16
"Description": "This is a cool Tshirt",
_16
"ReleaseDate": "2022-01-01T00:00:00",
_16
"IsVisible": true,
_16
"IsActive": true,
_16
"TaxCode": "",
_16
"MetaTagDescription": "tshirt black",
_16
"ShowWithoutStock": true,
_16
"Score": 1
_16
}

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