VTEX SKU Specification API

openapi: 3.2.0
info:
  title: VTex Catalog SKU Specification API
  description: '> Check the new Catalog onboarding guide.'
  version: '1.0'
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
security:
- appKey: []
  appToken: []
- VtexIdclientAutCookie: []
tags:
- name: SKU Specification
paths:
  /api/catalog/pvt/stockkeepingunit/{skuId}/specification:
    get:
      tags:
      - SKU Specification
      summary: VTex Get SKU specifications
      description: 'Retrieves information about an SKU''s specifications.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Content | **SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom 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.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: skuId
        in: path
        required: true
        description: SKU's unique numerical identifier.
        schema:
          type: integer
          example: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SKUSpecificationResponse'
              example:
              - Id: 1505
                SkuId: 1234568387
                FieldId: 193
                FieldValueId: 360
                Text: Size 10
      operationId: getApiCatalogPvtStockkeepingunitBySkuIdSpecification
      x-operation-id-source: derived
    post:
      tags:
      - SKU Specification
      summary: VTex Associate SKU specification
      description: 'Associates a previously created specification to an SKU.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Content | **SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom 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.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: skuId
        in: path
        required: true
        description: SKU's unique numerical identifier.
        schema:
          type: integer
          example: 1234568387
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - FieldId
              properties:
                FieldId:
                  type: integer
                  description: Specification field ID.
                  example: 13
                FieldValueId:
                  type: integer
                  description: Specification value ID. Required only for `FieldTypeId` as `5`, `6` and `7`.
                  example: 101
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SKUSpecificationResponse'
              example:
                Id: 1505
                SkuId: 1234568387
                FieldId: 193
                FieldValueId: 360
                Text: Size 10
      operationId: postApiCatalogPvtStockkeepingunitBySkuIdSpecification
      x-operation-id-source: derived
    put:
      tags:
      - SKU Specification
      summary: VTex Update SKU specification
      description: 'Updates an existing specification on an existing SKU. This endpoint only updates the `FieldValueId`.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Content | **SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom 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.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: skuId
        in: path
        required: true
        description: SKU's unique numerical identifier.
        schema:
          type: integer
          example: 21
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - Id
              - FieldId
              - FieldValueId
              properties:
                Id:
                  type: integer
                  description: Specification and SKU association unique identifier. This field cannot be updated.
                  example: 65
                SkuId:
                  type: integer
                  description: SKU unique identifier. This field cannot be updated.
                  example: 21
                FieldId:
                  type: integer
                  description: Specification field unique identifier. This field cannot be updated.
                  example: 32
                FieldValueId:
                  type: integer
                  description: Specification value unique identifier. This field can only be updated with other values of the same `FieldId`.
                  example: 131
                Text:
                  type: string
                  description: Specification value name. This field is automatically updated if the `FieldValue` is updated. Otherwise, the value cannot be modified.
                  example: Red
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SKUSpecificationResponse'
              example:
              - Id: 1505
                SkuId: 1234568387
                FieldId: 193
                FieldValueId: 360
                Text: Size 10
      operationId: putApiCatalogPvtStockkeepingunitBySkuIdSpecification
      x-operation-id-source: derived
    delete:
      tags:
      - SKU Specification
      summary: VTex Delete all SKU specifications
      description: 'Deletes all SKU specifications.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Content | **SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom 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.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: skuId
        in: path
        required: true
        description: SKU's unique numerical identifier.
        schema:
          type: integer
          example: 1
      responses:
        '200':
          description: OK
      operationId: deleteApiCatalogPvtStockkeepingunitBySkuIdSpecification
      x-operation-id-source: derived
  /api/catalog/pvt/stockkeepingunit/{skuId}/specification/{specificationId}:
    delete:
      tags:
      - SKU Specification
      summary: VTex Delete SKU specification
      description: 'Deletes a specific SKU specification.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Content | **SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom 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.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: skuId
        in: path
        required: true
        description: SKU's unique numerical identifier.
        schema:
          type: integer
          example: 1
      - name: specificationId
        in: path
        required: true
        description: Specification's unique numerical identifier.
        schema:
          type: integer
          example: 1
      responses:
        '200':
          description: OK
      operationId: deleteApiCatalogPvtStockkeepingunitBySkuIdSpecificationBySpecificationId
      x-operation-id-source: derived
  /api/catalog/pvt/stockkeepingunit/{skuId}/specificationvalue:
    put:
      tags:
      - SKU Specification
      summary: VTex Associate SKU specification using specification name and group name
      description: 'Associates a specification to an SKU using specification name and group name. Automatically creates the informed group, specification and values if they had not been created before.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Content | **SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom 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.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: skuId
        in: path
        required: true
        description: SKU's unique numerical identifier.
        schema:
          type: integer
          example: 1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                FieldName: Size
                GroupName: Sizes
                RootLevelSpecification: true
                FieldValues:
                - M
              required:
              - FieldName
              - GroupName
              - RootLevelSpecification
              - FieldValues
              properties:
                FieldName:
                  type: string
                  description: Specification name. Limited to 100 characters.
                  example: Material
                GroupName:
                  type: string
                  description: Group name.
                  example: Composition
                RootLevelSpecification:
                  type: boolean
                  description: Root level specification.
                  example: true
                FieldValues:
                  type: array
                  description: Array of specification values. SKU specifications must contain only one value.
                  example:
                  - M
                  items:
                    type: string
                    description: Specification value.
                    example: M
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                example:
                - Id: 418
                  SkuId: 5
                  FieldId: 29
                  FieldValueId: 76
                  Text: M
                type: array
                description: Array with information of all SKU specifications.
                items:
                  type: object
                  description: Object with information of the specification.
                  properties:
                    Id:
                      type: integer
                      description: ID of the association of the SKU and the specification.
                    SkuId:
                      type: integer
                      description: SKU ID.
                    FieldId:
                      type: integer
                      description: Specification field ID.
                    FieldValueId:
                      type: integer
                      description: Current specification value ID.
                    Text:
                      type: string
                      description: Current specification value text.
      operationId: putApiCatalogPvtStockkeepingunitBySkuIdSpecificationvalue
      x-operation-id-source: derived
components:
  parameters:
    Accept:
      name: Accept
      in: header
      description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
      required: true
      style: simple
      schema:
        type: string
        default: application/json
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        default: application/json
  schemas:
    SKUSpecificationResponse:
      type: object
      properties:
        Id:
          type: integer
          description: ID of the association of the specification and the SKU. This ID is used to update or delete the specification.
        SkuId:
          type: integer
          description: SKU ID.
        FieldId:
          type: integer
          description: Specification field ID.
        FieldValueId:
          type: integer
          description: Specification value ID. Required only for `FieldTypeId` as `5`, `6` and `7`.
        Text:
          type: string
          description: Value of specification. Only for `FieldTypeId` different from `5`, `6` and `7`.
      example:
        Id: 1505
        SkuId: 1234568387
        FieldId: 193
        FieldValueId: 360
        Text: Size 10
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
      description: Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken
      description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    VtexIdclientAutCookie:
      type: apiKey
      in: header
      name: VtexIdclientAutCookie
      description: '[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.'