Erply Product Group 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 Product Group API
  contact: {}
  version: 2.36.5
tags:
- name: Product Group
paths:
  /v1/product/group:
    get:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Get Product Groups. The fields `quick_books_debit_account`, `quick_books_credit_account`, `reward_points` and `location_tax_rates` will be on the object only if there are values for them
      tags:
      - Product Group
      summary: Get Groups
      parameters:
      - description: skip n records
        name: skip
        in: query
        schema:
          type: integer
      - description: 'items to take, default: 20, max: 100000'
        name: take
        in: query
        schema:
          type: integer
      - description: the sort parameter is explained in the `Filtering & Sorting` section on top of the Swagger documentation
        name: sort
        in: query
        schema:
          type: string
      - description: the filter parameter is explained in the `Filtering & Sorting` section on top of the Swagger documentation
        name: filter
        in: query
        schema:
          type: string
      - description: optionally return total number of records in the X-Total-Count response header
        name: withTotalCount
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          headers:
            X-Total-Count:
              description: total number of records (ignores skip & take parameters)
              schema:
                type: uint
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/groupmodels.GroupResponse'
        '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'
    post:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Create Product Group
      tags:
      - Product Group
      summary: Create Product Group
      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/groupmodels.GroupRequest'
        description: productGroupRequest
        required: true
  /v1/product/group/bulk:
    post:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: each request contains the created resource data
      tags:
      - Product Group
      summary: Create groups in bulk
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.BulkResponseWithResults'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/groupmodels.BulkCreateGroupsRequest'
        description: bulk create request
        required: true
  /v1/product/group/bulk/get:
    post:
      security:
      - sk: []
      - cc: []
      - jwt: []
      tags:
      - Product Group
      summary: Get groups in bulk
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/groupmodels.BulkReadGroupsResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/parammodels.BulkReadRequest'
        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/product/group/external-ids:
    get:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: External IDs are the ones from different commerce systems. This endpoint enables the API user to read the external IDs of the Erply product groups.
      tags:
      - Product Group
      summary: Read external group IDs of Product Groups
      parameters:
      - description: up to 100 external IDs. Cannot be provided with the product group ID parameter
        name: externalIDs
        in: query
        schema:
          type: array
          items:
            type: string
      - description: up to 100 product group IDs. Cannot be provided with the external ID parameter
        name: groupIDs
        in: query
        schema:
          type: array
          items:
            type: string
      - description: integration name
        name: integrationName
        in: query
        schema:
          type: string
      - description: skip n records
        name: skip
        in: query
        schema:
          type: integer
      - description: 'items to take, default: 20, max: 100000'
        name: take
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/groupmodels.ExternalIDResponse'
        '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'
  /v1/product/group/external-ids/{groupIds}:
    delete:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Requesting the endpoint will delete all the external IDs of selected product groups. With the integrationName parameter you can delete only integration-specific external IDs.
      tags:
      - Product Group
      summary: Delete external group IDs of Product Groups
      parameters:
      - description: Specify the integration name to delete the external ID associated with the integration only.
        name: integrationName
        in: query
        schema:
          type: string
      - description: up to 100 semicolon delimited Group IDs
        name: groupIds
        in: path
        required: true
        schema:
          type: string
      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'
  /v1/product/group/external-ids/{groupId}:
    post:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: External IDs are the ones from different commerce systems. This endpoint enables the API user to attach the external IDs to the Erply product groups.
      tags:
      - Product Group
      summary: Attach external group ID to a Product Group
      parameters:
      - description: Group ID
        name: groupId
        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/groupmodels.ExternalIDRequest'
        description: external ID with the integration name
        required: true
    patch:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: 'External IDs are the ones from different commerce systems that have to be stored in ERPLY

        This call allows to update the external ID using the integration name and group ID.'
      tags:
      - Product Group
      summary: Update external group ID of a Product Group
      parameters:
      - description: Group ID
        name: groupId
        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/groupmodels.ExternalIDRequest'
        description: external ID with the integration name
        required: true
  /v1/product/group/indented:
    get:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: The result is a indented list of group ids and names sorted by orders and prefixed by the dash (―) sign if is a parent
      tags:
      - Product Group
      summary: Get Indented List of Groups
      parameters:
      - description: Language code (ISO 639). Return the name in the requested language or leave empty for account default language.
        name: lang
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/indentation.Result'
        '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'
  /v1/product/group/tree:
    get:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: 'Optionally you can get products that belong to each group

        You must specify the fields to you want to get from the groups and products (models can be found under GET /product/group and GET /product)'
      tags:
      - Product Group
      summary: Get Tree of product groups
      parameters:
      - description: You must specify the fields to you want to get from the groups and products (models can be found under GET /product/group and GET /product)
        name: groupFields
        in: query
        schema:
          type: array
          items:
            type: string
      - description: You must specify the fields to you want to get from the groups and products (models can be found under GET /product/group and GET /product)
        name: productFields
        in: query
        schema:
          type: array
          items:
            type: string
      - description: Optionally you can get products that belong to each group
        name: withProducts
        in: query
        schema:
          type: boolean
      - description: Optionally specify the language ISO 639-1 code for the translatable fields. Default is the default language of the account.
        name: languageCode
        in: query
        schema:
          type: string
      - description: skip n records
        name: skip
        in: query
        schema:
          type: integer
      - description: 'items to take, default: 20, max: 100000'
        name: take
        in: query
        schema:
          type: integer
      - description: optionally return total number of records in the X-Total-Count response header
        name: withTotalCount
        in: query
        schema:
          type: boolean
      - description: the sort parameter is explained in the `Filtering & Sorting` section on top of the Swagger documentation
        name: sort
        in: query
        schema:
          type: string
      - description: the filter parameter is explained in the `Filtering & Sorting` section on top of the Swagger documentation
        name: itemFilters
        in: query
        schema:
          type: string
      - description: the filter parameter is explained in the `Filtering & Sorting` section on top of the Swagger documentation
        name: productFilters
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/indentation.GroupTreeResultSample'
        '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'
  /v1/product/group/{groupId}/location-tax/{warehouseId}:
    delete:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Delete Location Specific Tax To Product Group
      tags:
      - Product Group
      summary: Delete Location Specific Tax From Product Group
      parameters:
      - description: group ID
        name: groupId
        in: path
        required: true
        schema:
          type: string
      - description: warehouse ID
        name: warehouseId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          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'
  /v1/product/group/{ids}:
    delete:
      security:
      - sk: []
      - cc: []
      - jwt: []
      tags:
      - Product Group
      summary: Delete Product Groups
      parameters:
      - description: up to 100 semicolon delimited Group IDs
        name: ids
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          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'
  /v1/product/group/{id}:
    put:
      security:
      - sk: []
      - cc: []
      - jwt: []
      tags:
      - Product Group
      summary: Update Product Group
      parameters:
      - description: Group ID
        name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          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/groupmodels.GroupRequest'
        description: productGroupRequest
        required: true
  /v1/product/group/{id}/location-tax:
    patch:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Add Location Specific Tax To Product Group
      tags:
      - Product Group
      summary: Add Location Specific Tax
      parameters:
      - description: group ID
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          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/groupmodels.LocationSpecificTaxRequest'
        description: productGroupRequest
        required: true
  /v1/product/group/{id}/move:
    put:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: 'position has to be one of the following:  `lastChild` | `before` | `after`'
      tags:
      - Product Group
      summary: Move Product Group
      parameters:
      - description: Group ID
        name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          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/models.MoveRequest'
        description: moveRequest
        required: true
  /v1/product/{ids}/additional-groups:
    get:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Get Product's Additional Groups
      tags:
      - Product Group
      summary: Get Product's Additional Groups
      parameters:
      - description: up to 100 semicolon delimited product IDs
        name: ids
        in: path
        required: true
        schema:
          type: string
      - description: skip n records
        name: skip
        in: query
        schema:
          type: integer
      - description: 'items to take, default: 20, max: 100000'
        name: take
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/groupmodels.AdditionalGroupsResponse'
        '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'
  /v1/product/{id}/additional-groups:
    put:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: this request allows you to attach or delete additional groups to the product. To delete just pass an empty IDs array
      tags:
      - Product Group
      summary: Attach Additional Groups to Product
      parameters:
      - description: product ID
        name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          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/groupmodels.AdditionalGroupRequest'
        description: group IDs
        required: true
components:
  schemas:
    indentation.GroupTreeResultSampleNoChildren:
      type: object
      properties:
        item:
          $ref: '#/components/schemas/groupmodels.GroupResponse'
        products:
          type: array
          items:
            $ref: '#/components/schemas/products.ProductResponse'
    responses.Response:
      type: object
      properties:
        id:
          type: integer
          example: 73
    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
    groupmodels.BulkReadGroupsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/groupmodels.BulkReadGroupsResponseItem'
    groupmodels.LocationSpecificTaxRequest:
      type: object
      properties:
        taxrate_id:
          type: integer
        warehouse_id:
          type: integer
    groupmodels.LocationTaxRate:
      type: object
      properties:
        tax_rate_id:
          type: integer
        warehouse_id:
          type: integer
    groupmodels.GroupResponse:
      type: object
      properties:
        added:
          description: Unix timestamp
          type: integer
          example: 1595230999
        addedby:
          description: username
          type: string
          example: k@erp.xyz
        changed:
          description: Unix timestamp
          type: integer
          example: 1595230999
        changedby:
          description: username
          type: string
          example: k@erp.xyz
        description:
          $ref: '#/components/schemas/Translatable'
        formula_identifier:
          type: string
        id:
          type: integer
        location_tax_rates:
          type: array
          items:
            $ref: '#/components/schemas/groupmodels.LocationTaxRate'
        name:
          description: /This field supports more languages. Please read Translatable names and descriptions block in the documentation.
          $ref: '#/components/schemas/Translatable'
        non_discountable:
          type: integer
        order:
          type: integer
        parent_id:
          type: integer
        quick_books_credit_account:
          type: string
        quick_books_debit_account:
          type: string
        reward_points:
          type: number
        show_in_webshop:
          type: integer
    parammodels.FilterJSON:
      type: object
      properties:
        fieldName:
          type: string
          example: group_id
        operandBefore:
          description: supported values are "and", "or"
          type: string
          example: or
        operator:
          type: string
          example: '='
        sliceValue:
          description: to be used if the value is a slice
          type: array
          items: {}
        value:
          type: object
    indentation.GroupTreeResultSample:
      type: object
      properties:
        children:
          type: array
          items:
            $ref: '#/components/schemas/indentation.GroupTreeResultSampleNoChildren'
        item:
          $ref: '#/components/schemas/groupmodels.GroupResponse'
        products:
          type: array
          items:
            $ref: '#/components/schemas/products.ProductResponse'
    products.ProductResponse:
      type: object
      properties:
        added:
          description: Unix timestamp
          type: integer
          example: 1595230999
        addedby:
          description: username
          type: string
          example: k@erp.xyz
        age_restriction:
          type: integer
        alcohol_percentage:
          type: string
        alcohol_registry_number:
          type: string
        batches:
          type: string
        brand_id:
          type: integer
        cashier_must_enter_price:
          description: boolean flag 0 or 1
          type: integer
        category_id:
          type: integer
        changed:
          description: Unix timestamp
          type: integer
          example: 1595230999
        changedby:
          description: username
          type: string
          example: k@erp.xyz
        code:
          type: string
        code2:
          type: string
        code3:
          type: string
        code5:
          type: string
        code6:
          type: string
        code7:
          type: string
        code8:
          type: string
        cost:
          type: number
        country_of_origin_id:
          type: integer
        delivery_time:
          type: string
        deposit_fee_amount:
          type: integer
        deposit_fee_id:
          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:
          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
        id:
          type: integer
        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:
          type: integer
        location_in_warehouse_text:
          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:
          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:
          type: integer
        price:
          type: number
        price_with_tax:
          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:
          type: string
        supplier_id:
          type: integer
        tax_free:
          description: boolean flag 0 or 1
          type: integer
        tax_rate_id:
          type: integer
        transport_packag

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