Erply Matrix Product Variation API

openapi: 3.2.0
info:
  description: "\n\n## Overview\n\n\n\nThis application offers an API for managing assignments and tasks.\n\n\n\nGraphQL endpoint for the same API is [also available](/graph)\n\n\n\n<details><summary>Authentication</summary>\n\n\n\n> \n\n> Authenticate using your Erply credentials and get a sessionKey. This sessionKey and your Erply clientCode must be provided in the HTTP headers of every request. You do not have to authenticate against this API - valid Erply sessionKey-s from other sources are also acceptable. To authenticate using this API, use the `POST /api/v1/auth` endpoint.\n\n>\n\n</details>\n\n"
  title: assignments Assortment Matrix Product Variation API
  contact: {}
  version: 2.36.5
tags:
- name: Matrix Product Variation
paths:
  /v1/matrix/product/variation/bulk:
    post:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Each request body is a variation to create. The parameters to generate the product code/code2 automatically is embedded into the request body as the `generateCodeAutomatically` & `generateCode2Automatically` fields.
      tags:
      - Matrix Product Variation
      summary: Create variations in bulk
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.BulkResponseWithResults'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/matrixmodels.VariationBulkCreateRequest'
        description: bulk create request
        required: true
    patch:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: each request item contains the updated resource data
      tags:
      - Matrix Product Variation
      summary: Change variation parents in bulk
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.BulkResponseWithResults'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/matrixmodels.VariationBulkChangeParentRequest'
        description: requests have the parameters that the original get request has, but in json format. This way you can apply the parameters to each request separately.
        required: true
  /v1/matrix/product/{id}/variation:
    post:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: 'Create specific variations (color/size combinations), each one as a separate product.

        `parent_product_id` field can be left empty on the variation.'
      tags:
      - Matrix Product Variation
      summary: Create Matrix Product Variation
      parameters:
      - description: matrix product ID
        name: id
        in: path
        required: true
        schema:
          type: integer
      - description: generate code automatically based on the preconfigured starting code or based on a generated code. If the code is not blank in the request, will override.
        name: generateCodeAutomatically
        in: query
        required: true
        schema:
          type: boolean
      - description: generate code2 (EAN/UPC) automatically based on the preconfigured starting code or based on a generated code. If the code is not blank in the request, will override.
        name: generateCode2Automatically
        in: query
        required: true
        schema:
          type: boolean
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.Response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.MessageResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.MessageResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/matrixmodels.CreateVariationRequest'
        description: Variation product and dimension value IDs
        required: true
  /v1/matrix/product/{productID}/variation/{variationID}/dimension-values:
    patch:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Update variation's dimensions values
      tags:
      - Matrix Product Variation
      summary: Update a matrix product variation's dimension values
      parameters:
      - description: matrix product ID
        name: productID
        in: path
        required: true
        schema:
          type: integer
      - description: matrix product variation ID
        name: variationID
        in: path
        required: true
        schema:
          type: integer
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.Response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.MessageResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.MessageResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.MessageResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/matrixmodels.ChangeVariationParentRequest'
        description: dimension value IDs
        required: true
  /v1/matrix/product/{productID}/variation/{variationID}/parent:
    patch:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: 'This endpoint solves 3 problems:

        1) the user can modify a variation product and REMOVE it''s matrix product (set it to 0),

        2) the user can move the variation to different matrix product, in that case attach dimension values (same or new)

        3) the user can associate a regular product with a matrix one (turn it into a variation) - in this case attach dimension values'
      tags:
      - Matrix Product Variation
      summary: Change Matrix Product Variation Parent
      parameters:
      - description: matrix product ID
        name: productID
        in: path
        required: true
        schema:
          type: integer
      - description: matrix product variation ID
        name: variationID
        in: path
        required: true
        schema:
          type: integer
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.Response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.MessageResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.MessageResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/matrixmodels.ChangeVariationParentRequest'
        description: dimension value IDs - the same as were on the variation, or new
        required: true
components:
  schemas:
    matrixmodels.ChangeVariationParentRequest:
      type: object
      properties:
        dimension_value_ids:
          description: Matrix variation can have up to 3 dimension values
          type: array
          items:
            type: integer
          example:
          - 1
          - 2
          - 3
    matrixmodels.VariationBulkCreateRequest:
      type: object
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/matrixmodels.VariationBulkCreateRequestItem'
    matrixmodels.VariationBulkCreateRequestItem:
      type: object
      properties:
        dimension_value_ids:
          description: Matrix variation can have up to 3 dimension values
          type: array
          items:
            type: integer
          example:
          - 1
          - 2
          - 3
        generateCode2Automatically:
          description: if true, the product code1 will be generated based on the user configuration or will generate the conde in case there is none
          type: boolean
        generateCodeAutomatically:
          description: if true, the product code will be generated based on the user configuration or will generate the conde in case there is none
          type: boolean
        matrixProductID:
          type: integer
        variation_product:
          description: product, type must be PRODUCT
          $ref: '#/components/schemas/products.ProductRequest'
    responses.Response:
      type: object
      properties:
        id:
          type: integer
          example: 73
    responses.MessageResponse:
      type: object
      properties:
        message:
          type: string
          example: some message
    ProductDescription:
      type: object
      properties:
        html:
          description: Description supports more languages. Please read Translatable names and descriptions block in the documentation.
          type: string
          example: <b>Very good product!</b>
        plain_text:
          description: Description supports more languages. Please read Translatable names and descriptions block in the documentation.
          type: string
          example: Very good product!
    matrixmodels.CreateVariationRequest:
      type: object
      properties:
        dimension_value_ids:
          description: Matrix variation can have up to 3 dimension values
          type: array
          items:
            type: integer
          example:
          - 1
          - 2
          - 3
        variation_product:
          description: product, type must be PRODUCT
          $ref: '#/components/schemas/products.ProductRequest'
    Description:
      type: object
      properties:
        en:
          description: Description supports more languages. Please read Translatable names and descriptions block in the documentation.
          $ref: '#/components/schemas/ProductDescription'
    Translatable:
      type: object
      properties:
        en:
          description: This field supports more languages. Please read Translatable names and descriptions block in the documentation.
          type: string
    responses.BulkResult:
      type: object
      properties:
        message:
          type: string
          example: some message
        resourceId:
          description: identifier of the REST-ful response
          type: integer
          example: 2
        resultId:
          description: identifier of the result item
          type: integer
          example: 2
    responses.BulkResponseWithResults:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/responses.BulkResult'
    matrixmodels.VariationBulkChangeParentRequest:
      type: object
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/matrixmodels.VariationBulkChangeParentRequestItem'
    matrixmodels.VariationBulkChangeParentRequestItem:
      type: object
      properties:
        dimension_value_ids:
          description: Matrix variation can have up to 3 dimension values
          type: array
          items:
            type: integer
          example:
          - 1
          - 2
          - 3
        productID:
          type: integer
        variationID:
          type: integer
    products.ProductRequest:
      type: object
      properties:
        age_restriction:
          type: integer
        alcohol_percentage:
          type: string
        alcohol_registry_number:
          type: string
        backup_id:
          type: integer
        batches:
          type: string
        brand_id:
          description: ID of product brand. To get the list of brandmodels, use getBrands.
          type: integer
        cashier_must_enter_price:
          description: boolean flag 0 or 1
          type: integer
        category_id:
          type: integer
        code:
          description: Product's code. Must be UNIQUE, unless the account is configured otherwise.
          type: string
        code2:
          description: Product's second code (by convention, EAN barcode). Must be UNIQUE, unless the account is configured otherwise.
          type: string
        code3:
          description: Third code of the item (note that this field may not be visible on product card by default).
          type: string
        code5:
          type: string
        code6:
          type: string
        code7:
          type: string
        code8:
          type: string
        cost:
          description: Cost is Product cost
          type: number
        country_of_origin_id:
          type: integer
        delivery_time:
          type: string
        deposit_fee_amount:
          type: integer
        deposit_fee_id:
          description: ContainerID is ID of another product, a beverage container that is always sold together with this item.
          type: integer
        description:
          $ref: '#/components/schemas/Description'
        displayed_in_webshop:
          description: 0 or 1
          type: integer
        excise_declaration_number:
          type: string
        extra_field1_id:
          type: integer
        extra_field2_id:
          type: integer
        extra_field3_id:
          type: integer
        extra_field4_id:
          type: integer
        family_id:
          type: integer
        formula_identifier:
          type: string
        gross_weight:
          description: GrossWeight is Item's gross weight (with packaging). Unit depends on region, check your Erply account (typically lbs or kg).
          type: number
        group_id:
          description: ID of product group. To get the list of product groups, use getProductGroups.
          type: integer
        group_package_ferrous_metal:
          type: number
        group_package_metal:
          type: number
        group_package_non_ferrous_metal:
          type: number
        group_package_paper:
          type: number
        group_package_plastic:
          type: number
        group_package_wood:
          type: number
        has_serial_numbers:
          type: integer
        height:
          type: number
        is_gift_card:
          description: 0 or 1
          type: integer
        is_lot_product:
          type: boolean
        is_regular_gift_card:
          description: boolean flag 0 or 1
          type: integer
        is_used_product:
          type: boolean
        labels_not_needed:
          description: boolean flag 0 or 1
          type: integer
        length:
          description: Length is Item's physical dimensions.
          type: number
        location_in_warehouse_id:
          description: LocationInWarehouseID is ID of selected location in warehouse.
          type: integer
        location_in_warehouse_text:
          description: LocationInWarehouseText is Product's specific text added to location in warehouse.
          type: string
        manufacturer_name:
          type: string
        name:
          description: /This field supports more languages. Please read Translatable names and descriptions block in the documentation.
          $ref: '#/components/schemas/Translatable'
        net_weight:
          description: NetWeight is Item's net weight. Unit depends on region, check your Erply account (typically lbs or kg).
          type: number
        non_discountable:
          description: 0 or 1
          type: integer
        non_refundable:
          description: 0 or 1
          type: integer
        non_stock_product:
          description: boolean flag 0 or 1
          type: integer
        packaging_type:
          type: string
        packing_not_required:
          type: integer
        parent_product_id:
          description: Parent product ID. Only for matrix variations (specific colors/sizes of a matrix item). See guidelines below.
          type: integer
        price:
          description: 'Price is just the default price of a product and the actual price applied in a particular location, to a particular customer, depends on price lists and promotions: https://learn-api.erply.com/concepts/pricing'
          type: number
        priority_group_id:
          type: integer
        product_item_level_promotions_disabled:
          type: integer
        product_reorder_multiples:
          type: integer
        revenue_account:
          type: string
        reward_points_not_allowed:
          description: boolean flag 0 or 1
          type: integer
        sales_package_cardboard:
          type: number
        sales_package_clear_brown_glass:
          type: number
        sales_package_green_other_glass:
          type: number
        sales_package_metal_al:
          type: number
        sales_package_metal_fe:
          type: number
        sales_package_other_metal:
          type: number
        sales_package_paper_and_cardboard_mono:
          description: Product package materials
          type: number
        sales_package_plastic_pet:
          type: number
        sales_package_plastic_pp_pe:
          type: number
        sales_package_wood:
          type: number
        serial_number:
          type: string
        shelf_life_days:
          type: integer
        sold_in_packages:
          type: integer
        status:
          description: 'Status is a classifier with four possible values: ''ACTIVE'' (DEFAULT), ''NO_LONGER_ORDERED'', ''NOT_FOR_SALE'' and ''ARCHIVED''.'
          type: string
          example: ACTIVE
        suggested_retail_price:
          type: number
        supplier_code:
          description: Supplier's product code
          type: string
        supplier_id:
          type: integer
        tax_free:
          description: boolean flag 0 or 1
          type: integer
        tax_rate_id:
          description: 'TaxRateID is just the default tax rate of a product and the actual tax applied in a particular location depends on multiple rules: https://learn-api.erply.com/concepts/taxes.'
          type: integer
        transport_package_cardboard:
          type: number
        transport_package_ferrous_metal:
          type: number
        transport_package_non_ferrous_metal:
          type: number
        transport_package_plastic:
          type: number
        transport_package_wood:
          type: number
        type:
          description: Product type, possible types are 'PRODUCT', 'BUNDLE', 'MATRIX', 'ASSEMBLY'. By default 'PRODUCT'.
          type: string
        unit_id:
          description: ID of product unit. To get the list of units, use getProductUnits.
          type: integer
        volume:
          description: Volume is Item's fluid volume, eg. for beverages or perfumery. Unit depends on locale, check your Erply account (typically mL or fl oz).
          type: number
        webshop_description:
          type: string
        webshop_keywords:
          type: string
        webshop_title:
          type: string
        webshop_url_slug:
          type: string
        width:
          type: number
  securitySchemes:
    AccessToken:
      type: apiKey
      name: accessToken
      in: header
    ErplyClientCode:
      type: apiKey
      name: clientCode
      in: header
    ErplyJWT:
      type: apiKey
      name: jwt
      in: header
    ErplySession:
      type: apiKey
      name: sessionKey
      in: header
    RequestKey:
      type: apiKey
      name: requestKey
      in: header