Learn how to create, update, and activate an SKU with the Catalog API.
This step-by-step guide will walk you through the process of creating, updating, and activating a Stock Keeping Unit (SKU) within the VTEX platform. An SKU represents a specific item in the inventory that customers can purchase, essentially serving as a unique product variation, such as a "long sleeve gray size S shirt."
Before you begin
Before you begin managing your SKUs, make sure you've completed the following steps:
- Create a Product: Your SKUs should be associated with an existing product. If you haven't created a product yet, refer to the Product for more information.
- Obtain API Credentials: Ensure you have a valid
appKeyandappTokenwith the necessary permissions to access the Catalog API. For more information, please refer to the Roles article.
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.
Creating an SKU
Send a request to the Create SKU endpoint to create a new SKU, considering the following points when building the request body:
IsActive: Ensure thatIsActiveis set tofalse. Activating it during creation will result in a400 Bad Requesterror.ActivateIfPossible: It's recommended to setActivateIfPossibleastrue,unless you plan to have an internal workflow to manually activate SKUs.- Alternate IDs: Provide at least one of the following IDs in the request body:
RefIdorEAN. You can also provide both if necessary.
When sending the request body, you can specify the desired SKU Id or let VTEX automatically generate it, as presented in the following.
Custom Id: Request body
If there is a need to create a new SKU with a specific custom Id, specify the Id (integer) in the request body.
Automatically generated ID: Request body
If there's no need to specify a custom Id, you can omit it from the request body, and VTEX will automatically generate the Id.
Updating an SKU
After successfully creating an SKU, you can update its details by sending a request to the Update SKU endpoint. To update an SKU, provide the SKU's unique skuId in the URL and include the updated information in the request body.
Activating an SKU
Activating an SKU means making it available for purchase in your store, allowing customers to browse, search, and buy the associated product. To be activated, ensure your SKU meets the following requirements:
- Alternate IDs: The SKU must have at least one of the following alternate IDs configured:
RefIdorEAN. - Image: The SKU must have at least one image associated with it. Use the Create SKU file endpoint to associate an image to an SKU.
- Specifications: If the SKU has specifications, they must be filled in.
- Kit: For kit SKUs, at least one component must be active.
- Product: The SKU must be associated with an active product, which, in turn, must be related to an active Brand and an active Category.
Once the SKU meets these requirements, you can activate it using one of the following methods: automatic or manual.
Automatic activation
If your SKU's IsActive is set to false and ActivateIfPossible is set to true, your SKU will automatically become active as soon as it is associated with an image or an active component.
Here's an overview of the necessary steps to implement automatic SKU activation:
- Create the SKU, setting
IsActiveasfalseandActivateIfPossibleastrue. - If the SKU is a kit, create and associate SKU components.
- Create and associate SKU files.
Manual activation
If your SKU's IsActive is set to false and ActivateIfPossible is set to false, send a request to the Update the SKU endpoint, setting IsActive as true.
Here's an overview of the necessary steps to implement manual SKU activation:
- Create the SKU, setting
IsActiveasfalseandActivateIfPossibleasfalse. - If the SKU is a kit, create and associate SKU components.
- Create and associate SKU files.
- Update the SKU as active, setting
IsActiveastrue.
Creating an SKU
Send a request to the Create SKU endpoint to create a new SKU, considering the following points when building the request body:
IsActive: Ensure thatIsActiveis set tofalse. Activating it during creation will result in a400 Bad Requesterror.ActivateIfPossible: It's recommended to setActivateIfPossibleastrue,unless you plan to have an internal workflow to manually activate SKUs.- Alternate IDs: Provide at least one of the following IDs in the request body:
RefIdorEAN. You can also provide both if necessary.
When sending the request body, you can specify the desired SKU Id or let VTEX automatically generate it, as presented in the following.
Custom Id: Request body
If there is a need to create a new SKU with a specific custom Id, specify the Id (integer) in the request body.
Automatically generated ID: Request body
If there's no need to specify a custom Id, you can omit it from the request body, and VTEX will automatically generate the Id.
Updating an SKU
After successfully creating an SKU, you can update its details by sending a request to the Update SKU endpoint. To update an SKU, provide the SKU's unique skuId in the URL and include the updated information in the request body.
Activating an SKU
Activating an SKU means making it available for purchase in your store, allowing customers to browse, search, and buy the associated product. To be activated, ensure your SKU meets the following requirements:
- Alternate IDs: The SKU must have at least one of the following alternate IDs configured:
RefIdorEAN. - Image: The SKU must have at least one image associated with it. Use the Create SKU file endpoint to associate an image to an SKU.
- Specifications: If the SKU has specifications, they must be filled in.
- Kit: For kit SKUs, at least one component must be active.
- Product: The SKU must be associated with an active product, which, in turn, must be related to an active Brand and an active Category.
Once the SKU meets these requirements, you can activate it using one of the following methods: automatic or manual.
Automatic activation
If your SKU's IsActive is set to false and ActivateIfPossible is set to true, your SKU will automatically become active as soon as it is associated with an image or an active component.
Here's an overview of the necessary steps to implement automatic SKU activation:
- Create the SKU, setting
IsActiveasfalseandActivateIfPossibleastrue. - If the SKU is a kit, create and associate SKU components.
- Create and associate SKU files.
Manual activation
If your SKU's IsActive is set to false and ActivateIfPossible is set to false, send a request to the Update the SKU endpoint, setting IsActive as true.
Here's an overview of the necessary steps to implement manual SKU activation:
- Create the SKU, setting
IsActiveasfalseandActivateIfPossibleasfalse. - If the SKU is a kit, create and associate SKU components.
- Create and associate SKU files.
- Update the SKU as active, setting
IsActiveastrue.
Note that additional configurations are necessary for a product and its SKUs to become visible in a store:
- Register a price for the SKU in the associated trade policy (sales channel). Refer to the Pricing guide for more information.
- Ensure you have at least one unit in stock. Manage your inventory by following the Fulfillment guide.
- Configure your storefront to display products correctly.