> ## Documentation Index
> Fetch the complete documentation index at: https://developer.jtl-software.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Adds a new variation (e.g., color, size) to an existing item. Variations allow customers to select different product options.



## OpenAPI

````yaml /openapi/2.1.json post /v2/itemdetails/variations/add
openapi: 3.0.0
info:
  title: JTL-WAWI API (Cloud)
  description: "JTL-Wawi-Version: 2.2.0-alpha.7351+Sha.7529201\r\n# Introduction\r\n\r\nWelcome to the JTL-WAWI technical API documentation. This guide is here to help developers understand how our REST API works and how it can be integrated into your existing systems. We'll delve into the details of authentication and data manipulation processes, providing clear examples along the way. Whether you're a developer or an IT professional, this documentation aims to give you a practical understanding, laying the groundwork for effectively using the JTL-WAWI API to enhance your processes.\r\n\r\n# Authentication\r\n\r\nYou register your application with the API by sending a POST request with the required information and corresponding keys. You can find the exact request details at https://developer.jtl-software.com/products/erp/swagger/appregistration. This information has to include the following:\r\n\r\n* AppId\r\n* DisplayName\r\n* Description\r\n* Version\r\n* ProviderName\r\n* ProviderWebsite\r\n* MandatoryApiScopes\r\n\r\nThis data is crucial for identifying and registering your application with the API. The API uses it to generate a temporary authentication ID that allows your application to access the necessary resources. After successful validation of this information, you will receive the API key required for future authentication and API requests.\r\n\r\nBefore you can begin the registration process, you must open JTL-Wawi (new interface) and start the registration process under 'Admin->App registration'. Only at this point are you authorised to send the first API call. This step in JTL-Wawi ensures that your application is properly registered and has permission to use the API.\r\n\r\nThe API will send you an authentication ID in the form of a token. Once you have received this token and successfully completed the registration in JTL-Wawi, you will send another request to the API by including this authentication ID in the URL path.\r\n\r\nAfter successful validation of this second request by the API and confirmation of the correct information, you will be provided with the actual API key. It is important to note that this API key will not be displayed again!\r\n\r\nThis API key will be used in the future to authenticate requests to the API. It is of utmost importance that you securely store the API key upon receipt, as it cannot be retrieved from any other location in the system."
  contact:
    name: JTL-Software-GmbH
    url: https://developer.jtl-software.com/
    email: partner@jtl-software.com
  version: '2.1'
  x-application-version: 2.2.0.0
servers:
  - url: https://api.jtl-cloud.com/erp
    description: Production Environment Cloud API Gateway
security: []
tags:
  - name: wms
    description: >-
      <p data-section-id='tag/wms' class='stable_summary'></p>Query all pick
      lists for a specific wms warehouse that are not completed.
  - name: WawiApp
    description: Development
  - name: warehouse
    description: >-
      <p data-section-id='tag/warehouse' class='stable_summary'></p>Query all
      warehouses
  - name: transactionStatus
    description: >-
      <p data-section-id='tag/transactionStatus'
      class='stable_summary'></p>Query all transaction status for sales order
  - name: tax
    description: >-
      <p data-section-id='tag/tax' class='stable_summary'></p>Returns the
      Taxrate for the given Item
  - name: item
    description: >-
      <p data-section-id='tag/item' class='stable_summary'></p>Query all tax
      classes
  - name: supplier
    description: >-
      <p data-section-id='tag/supplier' class='stable_summary'></p>Query all
      suppliers
  - name: stock
    description: >-
      <p data-section-id='tag/stock' class='stable_summary'></p>Query stocks for
      a specific item, warehouse or storage location
  - name: shippingmethod
    description: >-
      <p data-section-id='tag/shippingmethod' class='stable_summary'></p>Query
      all shipping methods
  - name: shipment
    description: >-
      <p data-section-id='tag/shipment' class='stable_summary'></p>Download a
      PDF Shipping Label from database by ID
  - name: salesorder
    description: >-
      <p data-section-id='tag/salesorder' class='stable_summary'></p>Query all
      sales orders
  - name: cancellationreason
    description: Planned
  - name: salesinvoicecorrection
    description: Development
  - name: return
    description: >-
      <p data-section-id='tag/return' class='beta_summary'></p>Create a new
      return with associated items and packages.
  - name: returnstate
    description: Planned
  - name: returnreason
    description: Planned
  - name: property
    description: >-
      <p data-section-id='tag/property' class='stable_summary'></p>Query all
      properties for items
  - name: printer
    description: >-
      <p data-section-id='tag/printer' class='beta_summary'></p>Returns all
      Installed Printers
  - name: paymentmethod
    description: >-
      <p data-section-id='tag/paymentmethod' class='stable_summary'></p>Query
      all payment methods
  - name: onholdreason
    description: >-
      <p data-section-id='tag/onholdreason' class='stable_summary'></p>Query all
      on hold reasons for sales orders
  - name: offer
    description: >-
      <p data-section-id='tag/offer' class='beta_summary'></p>Execute the
      printing of a Offer
  - name: Configuration
    description: Planned
  - name: manufacturer
    description: Development
  - name: label
    description: Development
  - name: invoice
    description: Planned
  - name: info
    description: >-
      <p data-section-id='tag/info' class='stable_summary'></p>Returns the
      status of the API
  - name: features
    description: >-
      <p data-section-id='tag/features' class='stable_summary'></p>Returns the
      available feature sets with release state and API version
  - name: Extensibility
    description: Planned
  - name: shipping
    description: Development
  - name: deliverynote
    description: Planned
  - name: customfields
    description: Development
  - name: customfield
    description: Development
  - name: customer
    description: >-
      <p data-section-id='tag/customer' class='stable_summary'></p>Query all
      customers
  - name: customerGroup
    description: >-
      <p data-section-id='tag/customerGroup' class='stable_summary'></p>Query
      all customer groups
  - name: customerCategory
    description: >-
      <p data-section-id='tag/customerCategory' class='stable_summary'></p>Query
      all customer categories
  - name: creditnote
    description: >-
      <p data-section-id='tag/creditnote' class='beta_summary'></p>Execute the
      printing of a CreditNote
  - name: company
    description: >-
      <p data-section-id='tag/company' class='stable_summary'></p>Query all
      companies
  - name: colorcodes
    description: >-
      <p data-section-id='tag/colorcodes' class='stable_summary'></p>Query all
      color codes for sales orders
  - name: category
    description: Development
  - name: appRegistration
    description: >-
      <p data-section-id='tag/appRegistration'
      class='deprecated_summary'></p>DEPRECATED seit Wawi 2.2.0: No-Op. Seit
      Wawi 2.1.0 registriert sich die Wawi selbst per JWT.
  - name: login
    description: >-
      <p data-section-id='tag/login' class='beta_summary'></p>Sends a request to
      log in the user / dynamically assign the WAWI user. Only use this request
      if your API uses SSL.
  - name: logout
    description: >-
      <p data-section-id='tag/logout' class='beta_summary'></p>Sends a request
      to log out the user
  - name: attribute
    description: Development
  - name: accountingData
    description: Planned
paths:
  /v2/itemdetails/variations/add:
    post:
      tags:
        - ItemdetailsCommand
      summary: >-
        Adds a new variation (e.g., color, size) to an existing item. Variations
        allow customers to select different product options.
      operationId: Itemdetails_AddItemVariation
      parameters:
        - name: x-tenant-id
          in: header
          required: true
          schema:
            type: string
            format: uuid
          description: The tenant ID for the target ERP instance.
        - name: x-runas
          in: header
          description: >-
            The User-Id (int or uuid) on whose behalf the request is executed.
            Requires scope 'Application.RunAs'.
          schema:
            type: string
        - name: x-companyid
          in: header
          description: >-
            The Company-Id (int or uuid) of the company on whose behalf the
            request is executed.
          schema:
            type: string
      requestBody:
        x-name: request
        description: Request parameters
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.AddItemVariationCommandRequest
        required: true
        x-position: 1
      responses:
        '200':
          description: Variation was successfully added to the item.
          content:
            application/json: {}
      security:
        - oauth2-authorization-code:
            - items.write
        - oauth2-client-credentials:
            - items.write
components:
  schemas:
    JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.AddItemVariationCommandRequest:
      type: object
      description: >-
        Adds a new variation (e.g., color, size) to an existing item. Variations
        allow customers to select different product options. - Request
      additionalProperties: false
      required:
        - ItemId
        - Variation
      properties:
        itemId:
          $ref: '#/components/schemas/JTL.Data.Contracts.Keys.ArtikelKey'
          description: >-
            Unique ID of the item to be modified - this key is used for all
            further operations with the item.
        variation:
          $ref: >-
            #/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.CreateVariation
          description: >-
            The variation to add including type (selectbox, radio, etc.),
            descriptions in multiple languages, and optional variation values.
    JTL.Data.Contracts.Keys.ArtikelKey:
      type: string
      format: uuid
      example: b45f6432-2462-4c6f-b00f-1d9d01000000
      additionalProperties: false
    JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.CreateVariation:
      type: object
      description: 'Model Class: CreateVariation '
      additionalProperties: false
      required:
        - Descriptions
        - VariationType
      properties:
        variationId:
          $ref: '#/components/schemas/JTL.Data.Contracts.Keys.VariationKey'
          description: Id of the Variation
          example: b45f6432-2462-4c6f-b00f-1d9d01000000
        position:
          type: integer
          description: Position of this Variation in the List
          format: int32
        descriptions:
          type: array
          description: Descriptions of this Variation in multiple Languages
          items:
            $ref: >-
              #/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.CreateDescription
        values:
          type: array
          description: Values for this Variation
          items:
            $ref: >-
              #/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.CreateVariationValue
        variationType:
          $ref: >-
            #/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.VariationType
          description: Type of the Variation
    JTL.Data.Contracts.Keys.VariationKey:
      type: string
      format: uuid
      example: b45f6432-2462-4c6f-b00f-1d9d01000000
      additionalProperties: false
    JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.CreateDescription:
      type: object
      description: 'Model Class: CreateDescription '
      additionalProperties: false
      required:
        - LanguageIso
        - Name
      properties:
        languageIso:
          type: string
          description: >-
            ISO2 language code that determines the language for this item
            description (e.g., "DE" for German, "EN" for English).
        name:
          type: string
          description: Name of the Variation in the specific language
    JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.CreateVariationValue:
      type: object
      description: 'Model Class: CreateVariationValue '
      additionalProperties: false
      required:
        - Descriptions
      properties:
        variationValueId:
          $ref: '#/components/schemas/JTL.Data.Contracts.Keys.VariationWertKey'
          description: Id of the VariationValue
          example: b45f6432-2462-4c6f-b00f-1d9d01000000
        itemNumber:
          type: string
          description: Itemnumber for this variationvalue
        gTIN:
          type: string
          description: GTIN for this variationvalue
        weightOffset:
          type: number
          description: Offset for the weight of this variationvalue
          format: decimal
        descriptions:
          type: array
          description: Descriptions of this VariationValue in multiple Languages
          items:
            $ref: >-
              #/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.CreateDescription
        surcharges:
          $ref: >-
            #/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.CreateVariationValueSurcharges
          description: Surcharges of this VariationValue
        position:
          type: integer
          description: Position of this VariationValue in the List
          format: int32
        image:
          $ref: '#/components/schemas/JTL.Data.Contracts.Keys.BildKey'
          description: >-
            Image for this variation value. This image will be used as the main
            image for the variation combination if this variation value is part
            of it and the variation combination doesn't have its own image.
          example: b45f6432-2462-4c6f-b00f-1d9d01000000
    JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.VariationType:
      type: integer
      description: >-
        0 = Unknown, 1 = Selectbox, 2 = Radiobutton, 3 = Swatches, 4 = Textbox,
        5 = FreeText, 6 = MandatoryFreeText
      format: int32
      x-enumNames:
        - Unknown
        - Selectbox
        - Radiobutton
        - Swatches
        - Textbox
        - FreeText
        - MandatoryFreeText
      enum:
        - 0
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
    JTL.Data.Contracts.Keys.VariationWertKey:
      type: string
      format: uuid
      example: b45f6432-2462-4c6f-b00f-1d9d01000000
      additionalProperties: false
    JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.CreateVariationValueSurcharges:
      type: object
      description: 'Model Class: CreateVariationValueSurcharges '
      additionalProperties: false
      properties:
        defaultSurchargeNet:
          type: number
          description: >-
            Default Surcharge if there is none specified for a specific
            saleschannel + customergroup
          format: decimal
        customerGroupSurcharges:
          type: array
          description: >-
            Default Surcharges for specific customergroups in general,
            independent of saleschannel
          items:
            $ref: >-
              #/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.CreateCustomerGroupSurcharge
        salesChannelSurcharges:
          type: array
          description: Surcharge for specific saleschannels + customergroups
          items:
            $ref: >-
              #/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.CreateSalesChannelSurcharge
    JTL.Data.Contracts.Keys.BildKey:
      type: string
      format: uuid
      example: b45f6432-2462-4c6f-b00f-1d9d01000000
      additionalProperties: false
    JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.CreateCustomerGroupSurcharge:
      type: object
      description: 'Model Class: CreateCustomerGroupSurcharge '
      additionalProperties: false
      required:
        - CustomerGroupId
      properties:
        customerGroupId:
          $ref: '#/components/schemas/JTL.Data.Contracts.Keys.KundenGruppeKey'
          description: Id of the customergroup
        surcharge:
          type: number
          description: Surcharge for that customergroup
          format: decimal
        isActive:
          type: boolean
          description: >-
            Defines if the surcharges will be synchronized to online
            saleschannels. Does not apply for the default customer group
            surcharges, which are always synchronized when not overriden.
    JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.CreateSalesChannelSurcharge:
      type: object
      description: 'Model Class: CreateSalesChannelSurcharge '
      additionalProperties: false
      required:
        - SalesChannelId
        - Surcharges
      properties:
        salesChannelId:
          $ref: '#/components/schemas/JTL.Wawi.Rest.Contracts.Models.SalesChannelId'
          description: Id of the saleschannel
        surcharges:
          type: array
          description: Contains the surcharges for that saleschannel and customergroup
          items:
            $ref: >-
              #/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.CreateCustomerGroupSurcharge
    JTL.Data.Contracts.Keys.KundenGruppeKey:
      type: string
      format: uuid
      example: b45f6432-2462-4c6f-b00f-1d9d01000000
      additionalProperties: false
    JTL.Wawi.Rest.Contracts.Models.SalesChannelId:
      type: string
      description: >-
        Represents a unique identifier for a sales channel, encapsulating
        various platform-specific keys such as shop,

        user, or channel identifiers.
      additionalProperties: false
  securitySchemes:
    oauth2-authorization-code:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.jtl-cloud.com/oauth2/auth
          tokenUrl: https://auth.jtl-cloud.com/oauth2/token
          scopes:
            items.read: Artikel lesen
            items.write: Artikel schreiben
            saleschannels.read: Verkaufskanäle lesen
            accountings.read: TbD
            all.read: Erlaubt der Anwendung, alle Daten zu lesen.
            cusomters.read: TbD
            customers.read: TbD
            customers.write: TbD
            customfields.read: TbD
            customfields.write: TbD
            deliveries.read: TbD
            deliveries.write: TbD
            deliverynotes.print: TbD
            deliverynotes.read: TbD
            deliverynotes.write: TbD
            extensibility.integration: TbD
            inventories.read: TbD
            inventories.write: TbD
            invoices.print: TbD
            invoices.read: TbD
            invoices.write: TbD
            labels.read: TbD
            labels.write: TbD
            offers.print: TbD
            offers.read: TbD
            orders.read: TbD
            picklists.read: TbD
            picklists.write: TbD
            returns.read: TbD
            returns.write: TbD
            salesinvoicecorrections.print: TbD
            salesinvoicecorrections.read: TbD
            salesinvoicecorrections.write: TbD
            salesorders.print: TbD
            salesorders.read: TbD
            salesorders.write: TbD
            suppliers.read: TbD
            system.config.read: TbD
            system.config.write: TbD
            system.read: TbD
            taxes.read: TbD
            warehouse.read: TbD
            wawiapp.all: Ermöglicht den Zugriff auf Wawi-App bezogene Opperationen.
            currencies.read: Ermöglicht den Lesezugriff auf Währungen.
            jera.read: Ermöglicht den Lesezugriff auf JERA-interne Endpunkte.
            paymentmethods.read: Ermöglicht den Lesezugriff auf Zahlungsarten.
            payments.write: Ermöglicht den Schreibzugriff auf Zahlungen.
            salesinvoices.read: Ermöglicht den Lesezugriff auf Verkaufsrechnungen.
            salesinvoices.write: Ermöglicht den Schreibzugriff auf Verkaufsrechnungen.
            salesquotations.read: Ermöglicht den Lesezugriff auf Verkaufsangebote.
            salesquotations.write: Ermöglicht den Schreibzugriff auf Verkaufsangebote.
            system.worker.read: Worker-Synchronisationen lesen
            system.worker.write: Worker-Synchronisationen schreiben
            resources.read: Ressourcen lesen
            resources.write: Ressourcen schreiben
            pps.read: Produktionsdaten lesen
            pps.write: Produktionsdaten schreiben
            inventory.read: Lagerbestand lesen
            inventory.write: Lagerbestand schreiben
            taxes.write: Steuern schreiben
            application.runas: >-
              Ermöglicht der Anwendung, Anfragen im Namen eines anderen
              Benutzers auszuführen.
    oauth2-client-credentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.jtl-cloud.com/oauth2/token
          scopes:
            items.read: Artikel lesen
            items.write: Artikel schreiben
            saleschannels.read: Verkaufskanäle lesen
            accountings.read: TbD
            all.read: Erlaubt der Anwendung, alle Daten zu lesen.
            cusomters.read: TbD
            customers.read: TbD
            customers.write: TbD
            customfields.read: TbD
            customfields.write: TbD
            deliveries.read: TbD
            deliveries.write: TbD
            deliverynotes.print: TbD
            deliverynotes.read: TbD
            deliverynotes.write: TbD
            extensibility.integration: TbD
            inventories.read: TbD
            inventories.write: TbD
            invoices.print: TbD
            invoices.read: TbD
            invoices.write: TbD
            labels.read: TbD
            labels.write: TbD
            offers.print: TbD
            offers.read: TbD
            orders.read: TbD
            picklists.read: TbD
            picklists.write: TbD
            returns.read: TbD
            returns.write: TbD
            salesinvoicecorrections.print: TbD
            salesinvoicecorrections.read: TbD
            salesinvoicecorrections.write: TbD
            salesorders.print: TbD
            salesorders.read: TbD
            salesorders.write: TbD
            suppliers.read: TbD
            system.config.read: TbD
            system.config.write: TbD
            system.read: TbD
            taxes.read: TbD
            warehouse.read: TbD
            wawiapp.all: Ermöglicht den Zugriff auf Wawi-App bezogene Opperationen.
            currencies.read: Ermöglicht den Lesezugriff auf Währungen.
            jera.read: Ermöglicht den Lesezugriff auf JERA-interne Endpunkte.
            paymentmethods.read: Ermöglicht den Lesezugriff auf Zahlungsarten.
            payments.write: Ermöglicht den Schreibzugriff auf Zahlungen.
            salesinvoices.read: Ermöglicht den Lesezugriff auf Verkaufsrechnungen.
            salesinvoices.write: Ermöglicht den Schreibzugriff auf Verkaufsrechnungen.
            salesquotations.read: Ermöglicht den Lesezugriff auf Verkaufsangebote.
            salesquotations.write: Ermöglicht den Schreibzugriff auf Verkaufsangebote.
            system.worker.read: Worker-Synchronisationen lesen
            system.worker.write: Worker-Synchronisationen schreiben
            resources.read: Ressourcen lesen
            resources.write: Ressourcen schreiben
            pps.read: Produktionsdaten lesen
            pps.write: Produktionsdaten schreiben
            inventory.read: Lagerbestand lesen
            inventory.write: Lagerbestand schreiben
            taxes.write: Steuern schreiben
            application.runas: >-
              Ermöglicht der Anwendung, Anfragen im Namen eines anderen
              Benutzers auszuführen.

````