VTEX Product API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Product API
  description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Anti-fraud Provider Protocol is a set of definitions to help you integrate your anti-fraud service API into VTEX platform.\r\n\r\nTo achieve this, you need to implement a web API (REST) following the specifications described in this documentation.\r\n\r\n>⚠️ You can also access our [template on GitHub](https://github.com/vtex-apps/antifraud-provider-example) to help you quickly develop your anti-fraud connector using the Anti-fraud Provider Protocol and VTEX IO.\r\n\r\nTo learn more about the Anti-fraud Provider Protocol, check our [developer guide](https://developers.vtex.com/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works).\r\n\r\n## Anti-fraud Provider API Index\r\n\r\n### Anti-fraud  Flow\r\n\r\n- `POST` [Send Anti-fraud Pre-Analysis Data (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/pre-analysis)\r\n- `POST` [Send Anti-fraud Data](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/transactions)\r\n- `PUT` [Update Anti-fraud Transactions (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#put-/transactions/-transactionId-)\r\n- `GET` [List Anti-fraud Provider Manifest](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/manifest)\r\n- `GET` [Get Anti-fraud Status](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/transactions/-transactions.id-)\r\n- `DELETE` [Stop Anti-fraud Analysis (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#delete-/transactions/-transactions.Id-)\r\n\r\n### OAuth Flow\r\n\r\n1. `POST` [Retrieve Token](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/authorization/token)\r\n2. `GET` [Redirect](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/redirect)\r\n3. `GET` [Return to VTEX](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorizationCode)\r\n4. `GET` [Get Credentials](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorization/credentials)"
  version: '1.0'
servers:
- url: https://{providerApiEndpoint}
  description: Anti-fraud provider endpoint URL.
  variables:
    providerApiEndpoint:
      description: Anti-fraud provider endpoint URL.
      default: '{providerApiEndpoint}'
tags:
- name: Product
paths:
  /api/catalog-seller-portal/products/{productId}:
    get:
      tags:
      - Product
      summary: VTex Get Product by ID
      description: " >\U0001F4D8 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: " >\U0001F4D8 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
                        description: SKU specifications. This field is mandatory, but nullable if there is only one SKU.
                        nullable: true
                        example:
                        - name: Color
                          value: Black
                        - name: Size
                          value: S
                        items:
                          type: object
                          required:
                          - name
                          - value
                          properties:
                            name:
                              type: string
                              description: SKU's specification name.
                              example: Color
                            value:
                              type: string
                              description: SKU's specification values.
                              example: Black
                      images:
                        type: array
                        description: Array of SKU's images IDs.
                        items:
                          type: string
                          description: SKU image ID.
                        example:
                        - vtex_logo.jpg
                origin:
                

# --- truncated at 32 KB (156 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-product-api-openapi.yml