Erply Products 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 Products API
  contact: {}
  version: 2.36.5
tags:
- description: 'NB: Product picture management is done with CDN API: https://learn-api.erply.com/new-apis/cdn-api'
  name: Products
  externalDocs:
    description: Detailed product documentation
    url: https://learn-api.erply.com/concepts/products
paths:
  /v1/product:
    get:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: 'Get Products, NB: Filtering & sorting is not supported for the following fields: length, delivery_time, packaging_type, alcohol_registry_number, alcohol_percentage

        batches, excise_declaration_number, tax_free, is_regular_gift_card, reward_points_not_allowed, non_stock_product, cashier_must_enter_price, labels_not_needed, deposit_fee_amount

        In filteration `group_id_with_sub` with `in` operator can be used in filters to get group ids with subgroups

        also `category_id_with_sub` with `in` operator can be used in filters to get category ids with subgroups'
      tags:
      - Products
      summary: 'Get Products, Product pictures: CDN API'
      parameters:
      - description: comma or semicolon separated list of fields to fetch
        name: fields
        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: 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/products.ProductResponse'
        '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: 'The field descriptions can be found under the model description. For that please click the Model button near the Example Value button under the product (body) parameter description.

        The group_id is a required field. Code, code2 must be unique or empty.

        Filtering won''t work for the price_with_tax field.'
      tags:
      - Products
      summary: 'Create a Product, Pictures: CDN API'
      parameters:
      - description: trim spaces on all text fields
        name: trimInput
        in: query
        schema:
          type: boolean
      - 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/products.ProductRequest'
        description: Product
        required: true
  /v1/product/bulk:
    put:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: The resourceId request field should be used for the product id in each request for the bulk update.
      tags:
      - Products
      summary: Update Products in bulk
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.BulkResponseWithResults'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/products.BulkUpdateProductRequest'
        description: Products to update with IDs
        required: true
    post:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: 'Each request body is a product to create. The parameters to generate the product code/code2 automatically is embedded into the request body as the `generateCodeAutomatically` & `generateCode2Automatically` fields.

        The body can contain up to 100 requests.'
      tags:
      - Products
      summary: Create Products in bulk
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.BulkResponseWithResults'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/products.BulkCreateProductRequest'
        description: Create Product Requests
        required: true
    patch:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: This API endpoint is to update the product field by field in bulk. You must provide the fields you want to update only
      tags:
      - Products
      summary: Update Product field by field in bulk
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.BulkResponseWithResults'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/products.BulkPatchUpdateProductRequest'
        description: products
        required: true
  /v1/product/bulk/get:
    post:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: 'Get Products in bulk, NB: Filtering & sorting is not supported for the following fields: length, delivery_time, packaging_type, alcohol_registry_number, alcohol_percentage

        batches, excise_declaration_number, tax_free, is_regular_gift_card, reward_points_not_allowed, non_stock_product, cashier_must_enter_price, labels_not_needed, deposit_fee_amount'
      tags:
      - Products
      summary: Get Products in bulk
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/products.BulkReadProductResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/parammodels.BulkReadRequestNoTotalCount'
        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/codes:
    get:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Get product codes
      tags:
      - Products
      summary: Get product codes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/products.AutoCodes'
        '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'
    patch:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Set/Update product codes - pass only the code(s) you need to set/update. Returns updated codes if any were updated
      tags:
      - Products
      summary: Set/Update product codes
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/products.AutoCodes'
        '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/products.CreateUpdateAutoCodes'
        description: codes
        required: true
  /v1/product/deleted/ids:
    get:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Get Deleted Product IDs
      tags:
      - Products
      summary: Get Deleted Product IDs
      parameters:
      - description: it' s a `UNIX timestamp`
        name: If-Modified-Since
        in: header
        schema:
          type: integer
      - 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
          headers:
            Timestamp:
              description: 'Server timestamp: UNIX timestamp when the execution of this API call started'
              schema:
                type: int
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
        '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/full-text-lookup:
    get:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Full text search is a more advanced way to search products
      tags:
      - Products
      summary: Lookup products
      parameters:
      - 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: text to lookup, must be at least 3 characters in length, if quotes are applied a string match is returned
        name: lookupPhrase
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/products.ProductResponse'
        '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/merge:
    post:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: '`useDiscardedProductRecipe` can be true only for Assembly, Bundle products if the kept product’s recipe is replaced by the discarded product’s recipe.

        `useDiscardedProductVariations` can be true only for Matrix products, if the kept product’s child products are replaced by the discarded product’s child products'
      tags:
      - Products
      summary: Merge a Product to another Product
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.MessageResponse'
        '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/products.ProductMergeRequest'
        description: ProductIDs
        required: true
  /v1/product/restore:
    post:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: 'The back-up ID can be passed to create product, update product & update product type endpoints as well as their bulk variants.

        Once passed, the system will keep a back-up of the products catalogue. To restore the catalogue, use this endpoint with the backupID.

        There can be only one back-up in the system.'
      tags:
      - Products
      summary: Restore products by backup ID
      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.BackupRequest'
        description: request
        required: true
  /v1/product/restore/info:
    get:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Return information on what would be restored with the restore products by backup ID call.
      tags:
      - Products
      summary: Get information on restore
      parameters:
      - description: backup id
        name: backupID
        in: query
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.BackupChanges'
        '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'
  /v1/product/{ids}:
    get:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Get Products in batch
      tags:
      - Products
      summary: Get Products in batch
      parameters:
      - description: can contain semicolon delimited 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
      - 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
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/products.ProductResponse'
        '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'
    delete:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: Deleting Products will delete all links to assortments and parameter values.
      tags:
      - Products
      summary: Delete Products
      parameters:
      - description: up to 100 semicolon delimited product 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/{id}:
    put:
      security:
      - sk: []
      - cc: []
      - jwt: []
      tags:
      - Products
      summary: Update Product
      parameters:
      - description: product ID
        name: id
        in: path
        required: true
        schema:
          type: integer
      - description: trim spaces on all text fields
        name: trimInput
        in: query
        schema:
          type: boolean
      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/products.ProductRequest'
        description: Product
        required: true
    patch:
      security:
      - sk: []
      - cc: []
      - jwt: []
      description: In this request you pass only the fields you want to update
      tags:
      - Products
      summary: Update Product field by field
      parameters:
      - description: product ID
        name: id
        in: path
        required: true
        schema:
          type: integer
      - description: trim spaces on all text fields
        name: trimInput
        in: query
        schema:
          type: boolean
      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/products.PatchUpdateProductRequest'
        description: Product
        required: true
components:
  schemas:
    responses.Response:
      type: object
      properties:
        id:
          type: integer
          example: 73
    products.AutoCodes:
      type: object
      properties:
        nextCode:
          type: integer
        nextCode2:
          type: integer
    products.PatchUpdateProductRequest:
      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:
          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
    products.BulkReadProductResponseItem:
      type: object
      properties:
        message:
          type: string
          example: some message
        products:
          type: array
          items:
            $ref: '#/components/schemas/products.ProductResponse'
        resultId:
          description: id of the response item
          type: integer
        totalCount:
          description: total number of records (ignores skip & take parameters)
          type: integer
    products.BulkCreateProductRequest:
      type: object
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/products.BulkCreateProductRequestItem'
    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
    products.BulkCreateProductRequestItem:
      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
      

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