VTEX Specification Field API

openapi: 3.2.0
info:
  title: VTex Catalog Specification Field 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: Specification Field
paths:
  /api/catalog_system/pub/specification/fieldGet/{fieldId}:
    get:
      tags:
      - Specification Field
      summary: VTex Get specification field
      description: 'Retrieves details from a specification field by this field''s ID.

        >⚠️ This is a legacy endpoint. We recommend using Get specification instead.


        ## 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 | Commercial | **SKU management** |


        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.'
      operationId: SpecificationsField
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: fieldId
        in: path
        description: Specification field ID.
        required: true
        style: simple
        schema:
          type: integer
          example: 88
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                Name: Material
                CategoryId: 4
                FieldId: 88
                IsActive: true
                IsRequired: true
                FieldTypeId: 1
                FieldTypeName: Texto
                FieldValueId: null
                Description: Composition of the product.
                IsStockKeepingUnit: false
                IsFilter: true
                IsOnProductDetails: false
                Position: 1
                IsWizard: false
                IsTopMenuLinkActive: false
                IsSideMenuLinkActive: true
                DefaultValue: null
                FieldGroupId: 20
                FieldGroupName: Clothes specifications
              schema:
                type: object
                properties:
                  Name:
                    type: string
                    description: Specification field name.
                  FieldId:
                    type: integer
                    description: Specification field ID.
                  IsActive:
                    type: boolean
                    description: Enable (`true`) or disable (`false`) specification.
                  IsRequired:
                    type: boolean
                    description: Makes the specification mandatory (`true`) or optional (`false`).
                  FieldTypeId:
                    type: integer
                    description: Field type ID can be `1 - Text`, `2 - Multi-Line Text`, `4 - Number`, `5 - Combo`, `6 - Radio`, `7 - Checkbox`, `8 - Indexed Text`, `9 - Indexed Multi-Line Text`.
                  FieldTypeName:
                    type: string
                    description: Field type name, which can be `Text`, `Multi-Line Text`, `Number`, `Combo`, `Radio`, `Checkbox`, `Indexed Text` or `Indexed Multi-Line Text`.
                  FieldValueId:
                    type:
                    - integer
                    - 'null'
                    description: Specification value ID.
                  Description:
                    type:
                    - string
                    - 'null'
                    deprecated: true
                  IsStockKeepingUnit:
                    type: boolean
                    description: If `true`, it will be added as a SKU specification. If `false`, it will be added as a product specification field.
                  IsFilter:
                    type: boolean
                    description: 'Store Framework - Deprecated.

                      Legacy CMS Portal - To allow the specification to be used as a facet (filter) on the search navigation bar.'
                  IsOnProductDetails:
                    type: boolean
                    description: 'Store Framework - Deprecated.

                      Legacy CMS Portal -If specification is visible on the product page.'
                  Position:
                    type: integer
                    description: 'Store Framework - Deprecated.

                      Legacy CMS Portal - This position number is used in ordering the specifications both in the navigation menu and in the specification listing on the product page.'
                  IsWizard:
                    type:
                    - boolean
                    - 'null'
                    deprecated: true
                    description: Deprecated field.
                  IsTopMenuLinkActive:
                    type: boolean
                    description: 'Store Framework - Deprecated.

                      Legacy CMS Portal - To make the specification visible in the store''s upper menu.'
                  IsSideMenuLinkActive:
                    type: boolean
                    description: 'Store Framework - Deprecated.

                      Legacy CMS Portal - To make the specification field clickable in the search navigation bar.'
                  DefaultValue:
                    type:
                    - string
                    - 'null'
                    description: Specification default value.
                  FieldGroupId:
                    type: integer
                    description: ID of the group of specifications that contains the new specification.
                  FieldGroupName:
                    type: string
                    description: Specification field group name.
      deprecated: false
  /api/catalog_system/pvt/specification/field:
    post:
      tags:
      - Specification Field
      summary: VTex Create specification field
      description: 'Creates a specification field in a category.

        >⚠️ This is a legacy endpoint. We recommend using Create specification instead.


        ## 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 | Commercial | **SKU management** |


        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.'
      operationId: SpecificationsInsertField
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecificationsInsertFieldRequest'
            example:
              Name: Material
              CategoryId: 4
              FieldId: 88
              IsActive: true
              IsRequired: true
              FieldTypeId: 1
              FieldValueId: 1
              IsStockKeepingUnit: false
              Description: Composition of the product.
              IsFilter: true
              IsOnProductDetails: false
              Position: 1
              IsWizard: false
              IsTopMenuLinkActive: true
              IsSideMenuLinkActive: true
              DefaultValue: null
              FieldGroupId: 20
              FieldGroupName: Clothes specifications
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              example: 89
              schema:
                type: integer
                description: Specification field ID.
      deprecated: false
    put:
      tags:
      - Specification Field
      summary: VTex Update specification field
      description: 'Updates a specification field in a category.

        >⚠️ This is a legacy endpoint. We recommend using Update specification instead.


        ## 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 | Commercial | **SKU management** |


        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.'
      operationId: SpecificationsInsertFieldUpdate
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecificationsInsertFieldUpdateRequest'
            example:
              FieldId: 89
              Name: Material
              CategoryId: 4
              IsActive: true
              IsRequired: true
              FieldTypeId: 1
              Description: Composition of the product.
              IsStockKeepingUnit: false
              IsFilter: true
              IsOnProductDetails: true
              Position: 1
              IsWizard: false
              IsTopMenuLinkActive: false
              IsSideMenuLinkActive: false
              DefaultValue: Cotton
              FieldGroupId: 20
              FieldGroupName: Clothes specifications
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              example: 89
              schema:
                type: integer
                description: Specification field ID.
      deprecated: false
components:
  schemas:
    SpecificationsInsertFieldUpdateRequest:
      required:
      - Name
      - CategoryId
      - IsActive
      - FieldId
      - IsRequired
      - FieldTypeId
      - Description
      - IsStockKeepingUnit
      - IsWizard
      - IsFilter
      - IsOnProductDetails
      - Position
      - IsTopMenuLinkActive
      - IsSideMenuLinkActive
      - DefaultValue
      - FieldGroupId
      - FieldGroupName
      type: object
      properties:
        Name:
          type: string
          description: Specification field ID.
        CategoryId:
          type:
          - integer
          - 'null'
          description: Category ID.
        FieldId:
          type:
          - integer
          - 'null'
          description: Specification field ID.
        IsActive:
          type: boolean
          description: Enables(`true`) or disables (`false`) the specification field.
          example: true
        IsRequired:
          type: boolean
          description: Makes the specification field mandatory (`true`) or optional (`false`).
        FieldTypeId:
          type: integer
          format: int32
          description: Specification field type ID.
        FieldValueId:
          type:
          - integer
          - 'null'
          description: Specification field value ID.
        Description:
          type:
          - string
          - 'null'
          description: Specification field description.
        IsStockKeepingUnit:
          type: boolean
          description: If `true`, it will be added as a SKU specification field. If `false`, it will be added as a product specification field.
        IsFilter:
          type: boolean
          description: 'Store Framework - Deprecated.

            Legacy CMS Portal - To allow the specification to be used as a facet (filter) on the search navigation bar.'
        IsOnProductDetails:
          type: boolean
          description: 'Store Framework - Deprecated.

            Legacy CMS Portal -If specification is visible on the product page.'
        Position:
          type: integer
          format: int32
          description: Specification field position.
        IsWizard:
          type: boolean
          description: Deprecated field.
          deprecated: true
        IsTopMenuLinkActive:
          type: boolean
          description: 'Store Framework - Deprecated.

            Legacy CMS Portal - To make the specification visible in the store''s upper menu.'
        IsSideMenuLinkActive:
          type: boolean
          description: 'Store Framework - Deprecated.

            Legacy CMS Portal - To make the specification field clickable in the search navigation bar.'
          example: false
        DefaultValue:
          type:
          - string
          - 'null'
          example: null
          description: Specification field default value.
        FieldGroupId:
          type: integer
          format: int32
          description: Specification field group ID.
          example: 1
        FieldGroupName:
          type: string
          description: Specification field group name.
          example: Name
    SpecificationsInsertFieldRequest:
      required:
      - Name
      - CategoryId
      - IsActive
      - FieldId
      - IsRequired
      - FieldTypeId
      - FieldValueId
      - Description
      - IsStockKeepingUnit
      - IsFilter
      - IsOnProductDetails
      - Position
      - IsWizard
      - IsTopMenuLinkActive
      - IsSideMenuLinkActive
      - DefaultValue
      - FieldGroupId
      - FieldGroupName
      type: object
      properties:
        Name:
          type: string
          description: Specification field name. Limited to 100 characters.
        CategoryId:
          type:
          - integer
          - 'null'
          description: Category ID.
        FieldId:
          type:
          - integer
          - 'null'
          description: Specification field ID.
        IsActive:
          type: boolean
          description: Defines if the specification field is active. The default value is `true`.
        IsRequired:
          type: boolean
          description: Makes the specification field mandatory (`true`) or optional (`false`).
        FieldTypeId:
          type: integer
          format: int32
          description: Specification field type ID.
        FieldValueId:
          type:
          - integer
          - 'null'
          description: Specification field value ID.
        Description:
          type:
          - string
          - 'null'
          description: Specification field description.
        IsStockKeepingUnit:
          type: boolean
          description: If `true`, it will be added as a SKU specification. If `false`, it will be added as a product specification field.
        IsFilter:
          type: boolean
          description: 'Store Framework - Deprecated.

            Legacy CMS Portal - To allow the specification to be used as a facet (filter) on the search navigation bar.'
        IsOnProductDetails:
          type: boolean
          description: 'Store Framework - Deprecated.

            Legacy CMS Portal -If specification is visible on the product page.'
        Position:
          type: integer
          format: int32
          description: Specification field position.
        IsWizard:
          type: boolean
          description: Deprecated field.
          deprecated: true
        IsTopMenuLinkActive:
          type: boolean
          description: 'Store Framework - Deprecated.

            Legacy CMS Portal - To make the specification visible in the store''s upper menu.'
        IsSideMenuLinkActive:
          type: boolean
          description: 'Store Framework - Deprecated.

            Legacy CMS Portal - To make the specification field clickable in the search navigation bar.'
        DefaultValue:
          type:
          - string
          - 'null'
          description: Specification field default value.
        FieldGroupId:
          type: integer
          format: int32
          description: Specification field group ID.
        FieldGroupName:
          type: string
          description: Specification field group name.
      example:
        Name: Material
        CategoryId: 4
        FieldId: 88
        IsActive: true
        IsRequired: true
        FieldTypeId: 1
        FieldValueId: 1
        IsStockKeepingUnit: false
        Description: Composition of the product.
        IsFilter: true
        IsOnProductDetails: false
        Position: 1
        IsWizard: false
        IsTopMenuLinkActive: true
        IsSideMenuLinkActive: true
        DefaultValue: null
        FieldGroupId: 20
        FieldGroupName: Clothes specifications
  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
  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.'