The VTEX Catalog API for Seller Portal provides endpoints for sellers to manage their product catalog within the VTEX seller portal experience. It enables product creation, category mapping, attribute management, and SKU synchronization between seller catalogs and marketplace catalogs.
openapi: 3.0.0
info:
title: VTex Catalog API - Seller Portal
description: "\r\nWith the Catalog API for Seller Portal, you will be able to create, edit and consult products and their variations, brands, and categories.\r\n\r\n>ℹ️ This API is part of the [Seller Portal Catalog](https://help.vtex.com/en/tutorial/how-the-seller-portal-catalog-works--7pMB6YOt6YQDQQbzFB4Pxp). This functionality is in the beta stage and can be discontinued at any moment at VTEX's discretion. VTEX will not be responsible for any instabilities caused by its use or discontinuity. If you have any questions, please contact [our Support Center](https://support.vtex.com/hc/en-us/requests).\r\n\r\n## Index\r\n\r\n### Product\r\n\r\n- `GET` [Get Product by ID](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#get-/api/catalog-seller-portal/products/-productId-)\r\n- `PUT` [Update Product](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#put-/api/catalog-seller-portal/products/-productId-)\r\n- `GET` [Get Product Description by Product ID](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#get-/api/catalog-seller-portal/products/-productId-/description)\r\n- `PUT` [Update Product Description by Product ID](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#put-/api/catalog-seller-portal/products/-productId-/description)\r\n- `GET` [Get Product by external ID, SKU ID, SKU external ID or slug](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#get-/api/catalog-seller-portal/products/-param-)\r\n- `POST` [Create Product](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#post-/api/catalog-seller-portal/products)\r\n\r\n### SKU\r\n\r\n- `GET` [Search for SKU](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#get-/api/catalog-seller-portal/skus/_search)\r\n- `GET` [Get List of SKUs](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#get-/api/catalog-seller-portal/skus/ids)\r\n\r\n### Brand\r\n\r\n- `GET` [Get List of Brands](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#get-/api/catalog-seller-portal/brands)\r\n- `POST` [Create a Brand](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#post-/api/catalog-seller-portal/brands)\r\n- `GET` [Get Brand by ID](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#get-/api/catalog-seller-portal/brands/-brandId-)\r\n- `PUT` [Update Brand](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#put-/api/catalog-seller-portal/brands/-brandId-)\r\n\r\n### Category\r\n\r\n- `GET` [Get Category Tree](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#get-/api/catalog-seller-portal/category-tree)\r\n- `PUT` [Update Category Tree](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#put-/api/catalog-seller-portal/category-tree)\r\n- `GET` [Get Category by ID](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#get-/api/catalog-seller-portal/category-tree/categories/-categoryId-)\r\n- `POST` [Create a Category](https://developers.vtex.com/docs/api-reference/catalog-api-seller-portal#post-/api/catalog-seller-portal/category-tree/categories)"
contact: {}
version: ''
servers:
- url: https://{accountName}.{environment}.com.br
description: VTEX server URL.
variables:
accountName:
description: Name of the VTEX account. Used as part of the URL.
default: apiexamples
environment:
description: Environment to use. Used as part of the URL.
enum:
- vtexcommercestable
default: vtexcommercestable
paths:
/api/catalog-seller-portal/products/{productId}:
get:
tags:
- Product
summary: VTex Get Product by ID
description: " >📘 This API is part of the [Seller Portal Catalog](https://help.vtex.com/en/tutorial/how-the-seller-portal-catalog-works--7pMB6YOt6YQDQQbzFB4Pxp). This functionality is in the beta stage and can be discontinued at any moment at VTEX's discretion. VTEX will not be responsible for any instabilities caused by its use or discontinuity. If you have any questions, please contact [our Support Center](https://support.vtex.com/hc/en-us/requests). \r\n\r\n Retrieves general information about a product by its ID. The response also has information about the product's SKUs.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| CatalogV2 | Management | **Product Read** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: GetProduct
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- name: productId
in: path
description: Product unique identifier number.
required: true
schema:
type: string
example: '189371'
responses:
'200':
description: OK
content:
application/json:
example:
id: '189371'
status: active
name: VTEX 10 Shirt
brandId: '1'
description: Description data for product.
brandName: AOC
categoryIds:
- '732'
categoryNames:
- /sandboxintegracao/Acessórios/
specs:
- name: Color
values:
- Black
- White
- name: Size
values:
- S
- M
- L
attributes:
- name: Fabric
value: Cotton
- name: Gender
value: Feminine
slug: /vtex-shirt
images:
- id: vtex_logo.jpg
url: https://vtxleo7778.vtexassets.com/assets/vtex.catalog-images/products/vtex_logo.jpg
alt: VTEX
skus:
- id: '182907'
externalId: '1909621862'
manufacturerCode: '1234567'
isActive: true
weight: 12
dimensions:
width: 1.5
height: 2.1
length: 1.6
RealWeight: 300
RealDimensions:
width: 1.5
height: 2.1
length: 1.6
specs:
- name: Color
value: Black
- name: Size
value: S
images:
- vtex_logo.jpg
- id: '182908'
externalId: '1909621862'
manufacturerCode: '1234568'
isActive: true
weight: 300
dimensions:
width: 1.5
height: 2.1
length: 1.6
specs:
- name: Color
value: White
- name: Size
value: L
images:
- vtex_logo.jpg
transportModal: '123'
taxCode: '100'
origin: vtxleo7778
createdAt: '2022-10-31T16:28:25.578067Z'
updatedAt: '2022-10-31T17:09:12.639088Z'
schema:
type: object
required:
- status
- name
- brandId
- brandName
- categoryIds
- categoryNames
- specs
- attributes
- slug
- images
- skus
- origin
- createdAt
- updatedAt
properties:
id:
type: string
description: Product's unique identifier number.
externalId:
type: string
description: Product reference unique identifier number in the store.
status:
type: string
description: Status of the product. Its values can be `active` or `inactive`.
name:
type: string
description: Product name. Use simple words and avoid other languages or complex writing. This field is essential for SEO and must respect the 150 character limit.
brandId:
type: string
description: Product's brand unique identifier number.
description:
type: string
description: Description data for product.
brandName:
type: string
description: Name of the brand associated with the product.
categoryIds:
type: array
description: Product's categories unique identifier numbers. It can have multiples IDs for each category and subcategories.
items:
type: string
description: Product's category unique identifier number.
categoryNames:
type: array
description: Names of the product's categories, displayed in a path format.
items:
type: string
description: Name of the product's category.
specs:
type: array
description: Specifications that will differentiate the possible product SKUs.
items:
type: object
description: SKU specifications.
required:
- name
- values
properties:
name:
type: string
description: Specification name.
values:
type: array
description: Specification values.
items:
type: string
description: Specification value.
attributes:
type: array
description: Attributes of the product. Attributes are additional properties used to create site browsing filters.
items:
type: object
description: Product attribute.
required:
- name
- value
properties:
name:
type: string
description: Attribute name.
value:
type: string
description: Attribute value.
slug:
type: string
description: Reference of the product in the URL of the store.
images:
type: array
description: Information of the images of the product.
items:
type: object
description: Information of the images of the product.
required:
- id
- url
properties:
id:
type: string
description: Image ID.
url:
type: string
description: 'Image URL, which must be in the following format: `https://{accountName}.vtexassets.com/assets/{path}`, saved using the [Catalog Images app](https://developers.vtex.com/vtex-developer-docs/docs/vtex-catalog-images).'
alt:
type: string
description: Image alternative description.
skus:
type: array
description: SKUs of the product.
items:
type: object
description: Informations about an SKU.
required:
- id
- isActive
- weight
- dimensions
- specs
- images
properties:
id:
type: string
description: SKU unique identifier number.
externalId:
type: string
description: Unique reference code created to improve the store's organization.
ean:
type: string
description: Unique SKU identification code (barcode), composed of up to 13 numeric characters.
manufacturerCode:
type: string
description: SKU reference code in the store.
isActive:
type: boolean
description: If the SKU is active (`true`) or inactive (`false`).
weight:
type: integer
description: SKU weight. It can be lighter than 1000 g.
dimensions:
type: object
description: SKU dimensions.
required:
- width
- height
- length
properties:
width:
type: number
description: SKU width.
height:
type: number
description: SKU height.
length:
type: number
description: SKU length.
RealWeight:
type: number
description: The product's real weight.
RealDimensions:
type: object
description: The product's real dimensions.
required:
- width
- height
- length
properties:
width:
type: number
description: The product's real width.
height:
type: number
description: The product's real height.
length:
type: number
description: The product's real length.
specs:
type: array
description: SKU specifications. This field is mandatory, but nullable if there is only one SKU.
nullable: true
items:
type: object
description: SKU specification.
required:
- name
- value
properties:
name:
type: string
description: SKU's specification name.
value:
type: string
description: SKU's specification values.
images:
type: array
description: SKU's images IDs.
items:
description: SKU image ID.
type: string
transportModal:
type: string
description: Transport modal of the product.
nullable: true
taxCode:
type: string
description: Product tax code.
nullable: true
origin:
type: string
description: Origin account of the product. It is not possible to alter products where the origin is `marketplace`.
createdAt:
type: string
description: Date when the product was created.
updatedAt:
type: string
description: Last date when the product was updated.
put:
tags:
- Product
summary: VTex Update Product
description: " >📘 This API is part of the [Seller Portal Catalog](https://help.vtex.com/en/tutorial/how-the-seller-portal-catalog-works--7pMB6YOt6YQDQQbzFB4Pxp). This functionality is in the Beta stage and can be discontinued at any moment at VTEX's discretion. VTEX will not be responsible for any instabilities caused by its use or discontinuity. If you have any questions, please contact [our Support Center](https://support.vtex.com/hc/en-us/requests). \r\n\r\n Updates an existing product and its SKUs.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| CatalogV2 | Management | **Product Write** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: PutProduct
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- name: productId
in: path
description: Product unique identifier number.
required: true
schema:
type: string
example: '189371'
requestBody:
content:
application/json:
schema:
type: object
required:
- status
- name
- brandId
- categoryIds
- specs
- attributes
- slug
- images
- skus
- origin
properties:
id:
type: string
description: Product's unique identifier number.
example: '189371'
externalId:
type: string
description: Product reference unique identifier number in the store.
example: sandboxintegracao-310117347
status:
type: string
description: Status of the product. Its values can be `active` or `inactive`.
example: active
name:
type: string
description: Product name. Use simple words and avoid other languages or complex writing. This field is essential for SEO and must respect the 150 character limit.
example: Camiseta VTEX 10
brandId:
type: string
description: Product's brand unique identifier number.
example: '1'
description:
type: string
description: New description data for SKU/product.
example: VTEX Shirt Black Size S Long Sleeze.
categoryIds:
type: array
description: Product's categories unique identifier numbers. It can have multiples IDs for each category and subcategories.
example:
- '732'
- '412'
items:
type: string
description: Product's category unique identifier number.
example: '732'
specs:
type: array
description: Specifications that will differentiate the possible product SKUs.
example:
- name: Color
values:
- Black
- White
- name: Size
values:
- S
- M
- L
items:
type: object
description: SKU specification.
required:
- name
- values
properties:
name:
type: string
description: Specification name.
example: Color
values:
type: array
description: Specification values.
example:
- Black
- White
items:
type: string
description: Specification value.
attributes:
type: array
description: Attributes of the product. Attributes are additional properties used to create site browsing filters.
example:
- name: Fabric
value: Cotton
- name: Gender
value: Feminine
items:
type: object
description: Product attribute.
required:
- name
- value
properties:
name:
type: string
description: Attribute name.
example: Fabric
value:
type: string
description: Attribute value.
example: Cotton
slug:
type: string
description: Reference of the product in the URL of the store.
example: /vtex-shirt
transportModal:
type: string
description: Transport modal of the product.
example: '1'
nullable: true
taxCode:
type: string
description: Product tax code.
example: '123'
nullable: true
images:
type: array
description: Information of the images of the product.
example:
- id: vtex_logo.jpg
url: https://vtxleo7778.vtexassets.com/assets/vtex.catalog-images/products/vtex_logo.jpg
alt: imagem
items:
type: object
description: Image information.
required:
- id
- url
properties:
id:
type: string
description: Image ID.
example: vtex_logo.jpg
url:
type: string
description: 'Image URL, which must be in the following format: `https://{accountName}.vtexassets.com/assets/{path}`, saved using the [Catalog Images app](https://developers.vtex.com/vtex-developer-docs/docs/vtex-catalog-images).'
example: https://mystore.vtexassets.com/assets/vtex.catalog-images/products/vtex_logo.jpg
alt:
type: string
description: Image alternative description.
example: imagem
skus:
type: array
description: SKUs of the product.
example:
- id: '182907'
name: VTEX Shirt Black Size S
externalId: '1909621862'
ean: 978-1909621862
manufacturerCode: '1234567'
isActive: true
weight: 12
dimensions:
width: 1.5
height: 2.1
length: 1.6
RealWeight: 1.6
RealDimensions:
width: 1.5
height: 2.1
length: 1.6
specs:
- name: Color
value: Black
- name: Size
value: S
images:
- vtex_logo.jpg
- id: '182908'
name: VTEX Shirt White Size L
externalId: '1909621862'
ean: 978-1909621862
manufacturerCode: '1234568'
isActive: true
weight: 300
dimensions:
width: 1.5
height: 2.1
length: 1.6
specs:
- name: Color
value: White
- name: Size
value: L
images:
- vtex_logo.jpg
items:
type: object
required:
- isActive
- weight
- dimensions
- specs
- images
properties:
id:
type: string
description: SKU unique identifier number. Do not include this field when adding a new SKU, only when editing existing SKUs.
example: '182907'
name:
type: string
description: SKU name. Use simple words and avoid other languages or complex writing. This field is essential for SEO and must respect the 150 character limit.
example: VTEX Shirt Black Size S
externalId:
type: string
description: Unique reference code created to improve the store's organization.
example: '1909621862'
description:
type: string
description: New description data for SKU or product.
ean:
type: string
description: Unique SKU identification code (barcode), composed of up to 13 numeric characters.
example: 978-1909621862
manufacturerCode:
type: string
description: SKU reference code in the store.
example: '1234567'
isActive:
type: boolean
description: Defines if the SKU is active (`true`) or inactive (`false`).
example: false
weight:
type: integer
description: SKU weight. It can be lighter than 1000 g.
example: 300
dimensions:
type: object
description: SKU dimensions.
example:
width: 1.5
height: 2.1
length: 1.6
required:
- width
- height
- length
properties:
width:
type: number
description: SKU width.
example: 1.5
height:
type: number
description: SKU height.
example: 2.1
length:
type: number
description: SKU length.
example: 1.6
RealWeight:
type: number
description: The product's real weight.
example: 1.6
RealDimensions:
type: object
description: The product's real dimensions.
required:
- width
- height
- length
properties:
width:
type: number
description: The product's real width.
example: 1.5
height:
type: number
description: The product's real height.
example: 2.1
length:
type: number
description: The product's real length.
example: 1.6
specs:
type: array
# --- truncated at 32 KB (131 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-catalog-api-seller-portal-openapi-original.yml