openapi: 3.0.0
info:
  title: Kinguin ESA - API for External Stores
  version: 1.0.0
  description: |
    API endpoints for managing purchases on Kinguin. This document provides documentation for versions `v1` and `v2`
servers:
  - url: https://gateway.sandbox.kinguin.net/esa
    description: Sandbox URL
  - url: https://gateway.kinguin.net/esa
    description: Production URL
tags:
  - name: Balance
  - name: Orders
  - name: Products
  - name: Dictionary
paths:
  /api/v1/balance:
    get:
      summary: Get Balance
      tags:
        - Balance
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/order:
    post:
      summary: Create Order
      tags:
        - Orders
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequestV1'
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
           description: Forbidden
        '422':
           description: Validation exception
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      summary: Get List of Orders
      description: |
        This endpoint provides orders only owned by store matched with `X-Api-Key` header
      tags:
        - Orders
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PageNumberQuery'
        - $ref: '#/components/parameters/PageLimitQuery'
        - $ref: '#/components/parameters/OrdersCreateAtFromQuery'
        - $ref: '#/components/parameters/OrdersCreateAtToQuery'
        - $ref: '#/components/parameters/OrdersKinguinIdQuery'
        - $ref: '#/components/parameters/OrdersProductIdQuery'
        - $ref: '#/components/parameters/OrdersOrderIdQuery'
        - $ref: '#/components/parameters/OrdersOrderExternalIdQuery'
        - $ref: '#/components/parameters/OrdersStatusQuery'
        - $ref: '#/components/parameters/OrdersPreorderQuery'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
           description: Forbidden
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/order/{orderId}:
    get:
      summary: Get Order Details
      description: |
        This endpoint provides order details only owned by store matched with `X-Api-Key` header
      tags:
        - Orders
      security:
        - ApiKeyAuth: []
      parameters:
        - name: orderId
          in: path
          description: Order ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v2/order:
    post:
      summary: Create Order
      tags:
        - Orders
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequestV2'
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v2/order/{orderId}/keys:
    get:
      summary: Get Keys
      tags:
        - Orders
      security:
        - ApiKeyAuth: []
      parameters:
        - name: orderId
          in: path
          description: Order ID
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/PageNumberQuery'
        - $ref: '#/components/parameters/PageLimitQuery'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SerialsResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v2/order/{orderId}/keys/return:
    post:
      summary: Return Keys
      description: |
        This endpoint returns all unclaimed or not delivered keys for given order. 
        A refund will be issued for returned keys.
      tags:
        - Orders
      security:
        - ApiKeyAuth: []
      parameters:
        - name: orderId
          in: path
          description: Order ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Keys returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnKeysResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/genres:
    get:
      summary: Get Genres
      tags:
        - Dictionary
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Genres'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/platforms:
    get:
      summary: Get Platforms
      tags:
        - Dictionary
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Platforms'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/regions:
    get:
      summary: Get Regions
      tags:
        - Dictionary
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Regions'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/products:
    get:
      summary: Get Products
      deprecated: true
      tags:
        - Products
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PageNumberQuery'
        - $ref: '#/components/parameters/PageLimitQuery'
        - $ref: '#/components/parameters/SortTypeQuery'
        - $ref: '#/components/parameters/ProductsSortByQuery'
        - $ref: '#/components/parameters/ProductsNameQuery'
        - $ref: '#/components/parameters/ProductsPriceFronQuery'
        - $ref: '#/components/parameters/ProductsPriceToQuery'
        - $ref: '#/components/parameters/ProductsPlatformQuery'
        - $ref: '#/components/parameters/ProductsGenreQuery'
        - $ref: '#/components/parameters/ProductsKinguinIdQuery'
        - $ref: '#/components/parameters/ProductsProductIdQuery'
        - $ref: '#/components/parameters/ProductsLanguagesQuery'
        - $ref: '#/components/parameters/ProductsPreorderQuery'
        - $ref: '#/components/parameters/ProductsActivePreorderQuery'
        - $ref: '#/components/parameters/ProductsRegionQuery'
        - $ref: '#/components/parameters/ProductsTagsQuery'
        - $ref: '#/components/parameters/ProductsUpdatedSinceQuery'
        - $ref: '#/components/parameters/ProductsUpdatedToQuery'
        - $ref: '#/components/parameters/ProductsWithTextQuery'
        - $ref: '#/components/parameters/ProductsMerchantNameQuery'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Products'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/products/{kinguinId}:
    get:
      summary: Get Product By KinguinId
      tags:
        - Products
      security:
        - ApiKeyAuth: []
      parameters:
        - name: kinguinId
          in: path
          description: Kinguin ID
          required: true
          schema:
            type: integer
        - $ref: '#/components/parameters/ProductsProjectionQuery'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v2/products:
    get:
      summary: Get Products
      tags:
        - Products
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PageNumberQuery'
        - $ref: '#/components/parameters/PageLimitQuery'
        - $ref: '#/components/parameters/SortTypeQuery'
        - $ref: '#/components/parameters/ProductsSortByQuery'
        - $ref: '#/components/parameters/ProductsNameQuery'
        - $ref: '#/components/parameters/ProductsPriceFronQuery'
        - $ref: '#/components/parameters/ProductsPriceToQuery'
        - $ref: '#/components/parameters/ProductsPlatformQuery'
        - $ref: '#/components/parameters/ProductsGenreQuery'
        - $ref: '#/components/parameters/ProductsKinguinIdQuery'
        - $ref: '#/components/parameters/ProductsProductIdQuery'
        - $ref: '#/components/parameters/ProductsLanguagesQuery'
        - $ref: '#/components/parameters/ProductsPreorderQuery'
        - $ref: '#/components/parameters/ProductsActivePreorderQuery'
        - $ref: '#/components/parameters/ProductsRegionQuery'
        - $ref: '#/components/parameters/ProductsTagsQuery'
        - $ref: '#/components/parameters/ProductsUpdatedSinceQuery'
        - $ref: '#/components/parameters/ProductsUpdatedToQuery'
        - $ref: '#/components/parameters/ProductsWithTextQuery'
        - $ref: '#/components/parameters/ProductsMerchantNameQuery'
        - $ref: '#/components/parameters/ProductsProjectionQuery'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductsV2'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v2/products/{productId}:
    get:
      summary: Get Product By ProductId
      tags:
        - Products
      security:
        - ApiKeyAuth: []
      parameters:
        - name: productId
          in: path
          description: Product ID
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/ProductsProjectionQuery'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
  schemas:
    BalanceResponse:
      type: object
      properties:
        total:
          type: number
          description: |
            Total available balance
    OrderRequestV1:
      type: object
      properties:
        products:
          type: array
          description: |
            Products to be ordered
          items:
            $ref: '#/components/schemas/OrderProductRequestV1'
          minItems: 1
          maxItems: 10
        orderExternalId:
          type: string
      required:
        - products
    OrderProductRequestV1:
      type: object
      description: |
        This schema is required only for API `v1`
      properties:
        kinguinId:
          type: integer
          minimum: 1
          description: |
            The product `kinguinId` identifier
        qty:
          type: integer
          minimum: 1
          maximum: 1000
          description: |
            The maximum value is allowed only for wholesale orders. Default maximum limit is 9
        price:
          type: number
          minimum: 0.01
          description: |
            The maximum amount to spend.
            The price can not be lower than cheapest price
        offerId:
          type: string
          description: |
            You can specify an offer you want to buy. If empty, then the cheapest offer will be chosen.
            This property is mandatory to use for wholesale orders
        keyType:
          $ref: '#/components/schemas/KeyType'
          description: |
            This property allows to select only specific type of keys
      required:
        - kinguinId
        - qty
        - price
    OrderRequestV2:
      type: object
      properties:
        products:
          type: array
          description: |
            Products to be ordered
          items:
            $ref: '#/components/schemas/OrderProductRequestV2'
          minItems: 1
          maxItems: 10
        orderExternalId:
          type: string
      required:
        - products
    OrderProductRequestV2:
      type: object
      description: |
        This schema is required only for API `v2`
      properties:
        productId:
          type: string
          description: |
            The product `productId` identifier
        qty:
          type: integer
          minimum: 1
          maximum: 1000
          description: |
            The maximum value is allowed only for wholesale orders. Default maximum limit is 9
        price:
          type: number
          minimum: 0.01
          description: |
            The maximum amount to spend.
            The price can not be lower than cheapest price
        offerId:
          type: string
          description: |
            You can specify an offer you want to buy. If empty, then the cheapest offer will be chosen.
            This property is mandatory to use for wholesale orders
        keyType:
          $ref: '#/components/schemas/KeyType'
          description: |
            This property allows to select only specific type of keys
      required:
        - productId
        - qty
        - price
    Order:
      type: object
      properties:
        totalPrice:
          type: number
          description: |
            The total price of whole order
        requestTotalPrice:
          type: number
          description: |
            The total price of order based on `price` sent in request
        paymentPrice:
          type: number
          description: |
            The amount of balance spent for an order
        totalQty:
          type: integer
          description: |
            The total number of keys
        status:
          $ref: '#/components/schemas/OrderStatus'
          description: |
            The current order status
        storeId:
          type: integer
          description: |
            The store identifier which owns the order
        createdAt:
          type: string
          description: |
            The order creation date
        orderId:
          type: string
          description: |
            The order ID
        kinguinOrderId:
          type: integer
          deprecated: true
          description: |
            This legacy parameter refers to the old platform
        orderExternalId:
          type: string
          description: |
            Your unique order identifier
        products:
          type: array
          description: |
            Ordered products
          items:
            $ref: '#/components/schemas/OrderProduct'
    OrderProduct:
      type: object
      properties:
        kinguinId:
          type: integer
          description: |
            The product `kinguinId` identifier
        productId:
          type: string
          description: |
            The product `productId` identifier
        offerId:
          type: string
          description: |
            Purchased offer identifier
        qty:
          type: integer
          description: |
            Product quantity
        name:
          type: string
          description: |
            The product name
        price:
          type: number
          description: |
            Unit purchase price
        totalPrice:
          type: number
          description: |
            Total purchase price
        requestPrice:
          type: number
          description: |
            The unit `price` sent in order request
        isPreorder:
          type: boolean
          description: |
            PRE-ORDER product
        releaseDate:
          type: string
          description: |
            The release date of PRE-ORDER
        keyType:
          $ref: '#/components/schemas/KeyType'
          description: |
            The `keyType` sent in order request
          nullable: true
          default: null
        keys:
          type: array
          description: |
            Product keys
          items:
            $ref: '#/components/schemas/Key'
    OrderStatus:
      type: string
      enum:
        - processing
        - completed
        - canceled
        - refunded
    KeyType:
      type: string
      enum:
        - text
    KeyStatus:
      type: string
      enum:
        - PENDING
        - PROCESSING
        - DELIVERED
        - RETURNED
        - REFUNDED
        - CANCELED
    Key:
      type: object
      properties:
        id:
          type: string
          description: |
            Item identifier
        status:
          $ref: '#/components/schemas/KeyStatus'
          description: |
            Item status
    MimeType:
      type: string
      enum:
        - text/plain
        - image/jpeg
        - image/png
        - image/gif
    Serial:
      type: object
      properties:
        id:
          type: string
          description: |
            Item identifier
        name:
          type: string
          description: |
            The product name
        type:
          $ref: '#/components/schemas/MimeType'
          description: |
            Content type
        serial:
          type: string
          description: |
            Key content. This value will be base64 encoded for all keys that are images
        kinguinId:
          type: integer
          description: |
            The product `kinguinId` identifier
        productId:
          type: string
          description: |
            The product `productId` identifier
        offerId:
          type: string
          description: |
            The purchased offer identifier
    SerialsResponse:
      type: array
      items:
        $ref: '#/components/schemas/Serial'
    ReturnKeysResponse:
      type: array
      items:
        $ref: '#/components/schemas/Key'
    YesNo:
      type: string
      enum:
        - "Yes"
        - "No"
    Yes:
      type: string
      enum:
        - "Yes"
    SortType:
      type: string
      enum:
        - asc
        - desc
    ErrorResponse:
      type: object
      properties:
        kind:
          $ref: '#/components/schemas/ErrorKind'
          description: |
            Type of error
        status:
          type: integer
          description: |
            HTTTP status code
        type:
          type: string
          description: |
            HTTTP status text
        method:
          type: string
          description: |
            HTTP method
        detail:
          type: string
          description: |
            Short error summary
        reason:
          $ref: '#/components/schemas/ProductUnavailableReason'
          description: |
            Cause of the error (present for ProductUnavailable)
        path:
          type: string
          description: |
            Used endpoint
        timestamp:
          type: string
          description: |
            Time of error
      additionalProperties: true
    ErrorKind:
      type: string
      enum:
        - ConstraintViolation
        - Error
        - HttpClient
        - Http
        - Authorization
        - InsufficientBalance
        - OrderFailed
        - Preorder
        - ProductUnavailable
        - OrderNotFound
        - OrderNotSupported
        - NoKeysToReturn
        - ProductNotFound
    ProductUnavailableReason:
      type: string
      enum:
        - NoStock
        - NoOffers
        - InvalidPrice
        - OfferRequired
        - WholesaleNotAvailable
        - NoTier
    OrdersResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        item_count:
          type: integer
    Region:
      type: object
      properties:
        id:
          type: integer
          description: |
            Region id
        name:
          type: string
          description: |
            Region name
    Regions:
      type: array
      items:
        $ref: '#/components/schemas/Region'
    Genres:
      type: array
      items:
        type: string
    Platforms:
      type: array
      items:
        type: string
    Product:
      type: object
      properties:
        kinguinId:
          type: integer
          description: |
            Product identifier.
            Should be used while creating order with API `v1`
        productId:
          type: string
          description: |
            Product identifier.
            Should be used while creating order with API `v2`
        cheapestOfferId:
          type: array
          items:
            type: string
          description: |
            List of all cheapest offers identifiers
        name:
          type: string
          description: |
            Product name
        originalName:
          type: string
          description: |
            Base name of product
        description:
          type: string
          description: |
            Product description
        developers:
          type: array
          items:
            type: string
          description: |
            List of product developers
        publishers:
          type: array
          items:
            type: string
          description: |
            List of product publishers
        genres:
          type: array
          items:
            type: string
          description: |
            List of product genres
        platform:
          type: string
          description: |
            Product platform
        releaseDate:
          type: string
          description: |
            Product release date
        qty:
          type: integer
          description: |
            Total cheapest offers quantity
        textQty:
          type: integer
          description: |
            Total cheapest offers text quantity
        totalQty:
          type: integer
          description: |
            Total offers quantity
        price:
          type: number
          description: |
            The cheapest offer price
        offers:
          type: array
          items:
            $ref: '#/components/schemas/Offer'
          description: |
            Available offers
        offersCount:
          type: integer
          description: |
            Total number of offers
        isPreorder:
          type: boolean
          description: |
            PRE-ORDER product
        metacriticScore:
          type: number
          description: |
            The Metacritic score
        regionalLimitations:
          type: string
          description: |
            Region name
        regionId:
          type: integer
          description: |
            Region id
        countryLimitation:
          type: array
          items:
            type: string
          description: |
            List of disallowed countries
        activationDetails:
          type: string
          description: |
            Activation details
        videos:
          type: array
          items:
            $ref: '#/components/schemas/Video'
          description: |
            Videos related with this product
        languages:
          type: array
          items:
            type: string
          description: |
            List of supported languages
        updatedAt:
          type: string
          description: |
            Last update date
        systemRequirements:
          type: array
          items:
            $ref: '#/components/schemas/SystemRequirement'
          description: |
            System requirements
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: |
            Tags
        merchantName:
          type: array
          items:
            type: string
          description: |
            List of merchant names from cheapest offers
        ageRating:
          type: string
          description: |
            PEGI or ESRB rating category
        steam:
          type: integer
          description: |
            Steam ID
        images:
          $ref: '#/components/schemas/Images'
          description: |
            List of images
    Images:
      type: object
      properties:
        screenshots:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        cover:
          $ref: '#/components/schemas/Image'
    Image:
      type: object
      properties:
        url:
          type: string
          description: |
            Main image
        thumbnail:
          type: string
          description: |
            Thumbnail
    Tag:
      type: string
      enum:
        - base
        - dlc
        - software
        - prepaid
        - indie valley
    Video:
      type: object
      properties:
        video_id:
          type: string
          description: |
            Video id
        video_url:
          type: string
          description: |
            Video url
    SystemRequirement:
      type: object
      properties:
        system:
          type: string
          description: |
            Name of operating system
        requirement:
          type: string
          description: |
            Requirements
    Offer:
      type: object
      properties:
        offerId:
          type: string
          description: |
            The offer identifier
        name:
          type: string
          description: |
            Product name
        price:
          type: number
          description: |
            Offer price
        qty:
          type: integer
          description: |
            Total quantity
        textQty:
          type: integer
          description: |
            Total text quantity
        availableQty:
          type: integer
          description: |
            Total uploaded quantity
        availableTextQty:
          type: integer
          description: |
            Total uploaded text quantity
        isPreorder:
          type: boolean
          description: |
            PRE-ORDER product
        releaseDate:
          type: string
          description: |
            Product release date
        wholesale:
          $ref: '#/components/schemas/Wholesale'
    Wholesale:
      type: object
      description: |
        Wholesale configuration
      properties:
        enabled:
          type: boolean
          description: |
            Enabled or disabled flag
        tiers:
          type: array
          description: |
            List of wholesale tiers
          items:
            $ref: '#/components/schemas/Tier'
          minItems: 0
          maxItems: 4
    Tier:
      type: object
      description: |
        Determines the price depending on the quantity
      properties:
        level:
          $ref: '#/components/schemas/TierLevel'
        price:
          type: number
          description: |
            Tier price. 
            This price should be provided in order request
    TierLevel:
      type: integer
      description: |
        Tier level
      enum:
        - 1
        - 2
        - 3
        - 4
      x-enum-descriptions:
        - 10+
        - 50+
        - 100+
        - 500+
    ProductsSortBy:
      type: string
      enum:
        - kinguinId
        - updatedAt
    OfferStock:
      title: Offer (stock)
      type: object
      additionalProperties: false
      description: |
        Offer fields returned when `projection=stock`
      properties:
        offerId:
          type: string
          description: |
            The offer identifier
        price:
          type: number
          description: |
            Offer price
        qty:
          type: integer
          description: |
            Total quantity
        textQty:
          type: integer
          description: |
            Total text quantity
        availableQty:
          type: integer
          description: |
            Total uploaded quantity
        availableTextQty:
          type: integer
          description: |
            Total uploaded text quantity
    ProductStock:
      title: Product (stock)
      type: object
      additionalProperties: false
      description: |
        Product fields returned when `projection=stock`
      properties:
        kinguinId:
          type: integer
          description: |
            Product identifier.
            Should be used while creating order with API `v1`
        productId:
          type: string
          description: |
            Product identifier.
            Should be used while creating order with API `v2`
        cheapestOfferId:
          type: array
          items:
            type: string
          description: |
            List of all cheapest offers identifiers
        qty:
          type: integer
          description: |
            Total cheapest offers quantity
        textQty:
          type: integer
          description: |
            Total cheapest offers text quantity
        totalQty:
          type: integer
          description: |
            Total offers quantity
        price:
          type: number
          description: |
            The cheapest offer price
        offers:
          type: array
          items:
            $ref: '#/components/schemas/OfferStock'
          description: |
            Available offers
        offersCount:
          type: integer
          description: |
            Total number of offers
        updatedAt:
          type: string
          description: |
            Last update date
    ProductResponse:
      description: |
        `Product` when `projection` is omitted or `default`.
        `ProductStock` when `projection` is `stock`.
      anyOf:
        - $ref: '#/components/schemas/Product'
        - $ref: '#/components/schemas/ProductStock'
    ProductsProjection:
      type: string
      description: |
        Controls which product fields are returned.
        Omitted or `default` returns `Product`.
        `stock` returns `ProductStock`.
      enum:
        - default
        - stock
    Products:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        item_count:
          type: integer
    ProductsV2:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            products:
              type: array
              items:
                $ref: '#/components/schemas/ProductResponse'
        page:
          type: object
          properties:
            totalElements:
              type: integer
            totalPages:
              type: integer
            number:
              type: integer
            size:
              type: integer
  parameters:
    PageLimitQuery:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    PageNumberQuery:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
    SortByQuery:
      name: sortBy
      in: query
      schema:
        type: string
    SortTypeQuery:
      name: sortType
      in: query
      schema:
        $ref: '#/components/schemas/SortType'
    OrdersCreateAtFromQuery:
      name: createdAtFrom
      in: query
      schema:
        type: string
      description: |
        Allowed formating: 
        - Y-m-d
        - Y-m-d H:i:s
        - Y-m-dTH:i:s
        - Y-m-dTH:i:s.uZ
        - Y-m-dTH:i:sP
    OrdersCreateAtToQuery:
      name: createdAtTo
      in: query
      schema:
        type: string
      description: |
        Allowed formating: 
        - Y-m-d
        - Y-m-d H:i:s
        - Y-m-dTH:i:s
        - Y-m-dTH:i:s.uZ
        - Y-m-dTH:i:sP
    OrdersKinguinIdQuery:
      name: kinguinId
      in: query
      schema:
        type: integer
      description: |
        The product `kinguinId` identifier
    OrdersProductIdQuery:
      name: productId
      in: query
      schema:
        type: string
      description: |
        The product `productId` identifier
    OrdersOrderIdQuery:
      name: orderId
      in: query
      schema:
        type: string
    OrdersOrderExternalIdQuery:
      name: orderExternalId
      in: query
      schema:
        type: string
    OrdersStatusQuery:
      name: status
      in: query
      schema:
        $ref: '#/components/schemas/OrderStatus'
    OrdersPreorderQuery:
      name: isPreorder
      in: query
      schema:
        $ref: '#/components/schemas/YesNo'
    ProductsNameQuery:
      name: name
      in: query
      schema:
        type: string
        minLength: 3
    ProductsPriceFronQuery:
      name: priceFrom
      in: query
      schema:
        type: number
        minimum: 0.01
      deprecated: true
    ProductsPriceToQuery:
      name: priceTo
      in: query
      schema:
        type: number
        minimum: 0.01
      deprecated: true
    ProductsPlatformQuery:
      name: platform
      in: query
      schema:
        type: string
    ProductsGenreQuery:
      name: genre
      in: query
      schema:
        type: string
    ProductsKinguinIdQuery:
      name: kinguinId
      in: query
      schema:
        type: string
      description: |
        Comma separated list of `kinguinId` identifiers
    ProductsProductIdQuery:
      name: productId
      in: query
      schema:
        type: string
      description: |
        Comma separated list of `productId` identifiers
    ProductsLanguagesQuery:
      name: languages
      in: query
      schema:
        type: string
      description: |
        Comma separated list of `language` names
    ProductsPreorderQuery:
      name: isPreorder
      in: query
      schema:
        $ref: '#/components/schemas/YesNo'
    ProductsActivePreorderQuery:
      name: activePreorder
      in: query
      schema:
        $ref: '#/components/schemas/Yes'
    ProductsRegionQuery:
      name: regionId
      in: query
      schema:
        type: integer
    ProductsTagsQuery:
      name: tags
      in: query
      schema:
        $ref: '#/components/schemas/Tag'
      description: |
        Comma separated list of `tag` names
    ProductsUpdatedSinceQuery:
      name: updatedSince
      in: query
      schema:
        type: string
      description: |
        Allowed formating: 
        - Y-m-d
        - Y-m-d H:i:s
        - Y-m-dTH:i:s
        - Y-m-dTH:i:s.uZ
        - Y-m-dTH:i:sP

        Not older than `7 days`
    ProductsUpdatedToQuery:
      name: updatedTo
      in: query
      schema:
        type: string
      description: |
        Allowed formating: 
        - Y-m-d
        - Y-m-d H:i:s
        - Y-m-dTH:i:s
        - Y-m-dTH:i:s.uZ
        - Y-m-dTH:i:sP

        Cannot be a future date
    ProductsWithTextQuery:
      name: withText
      in: query
      schema:
        $ref: '#/components/schemas/Yes'
    ProductsMerchantNameQuery:
      name: merchantName
      in: query
      schema:
        type: string
    ProductsSortByQuery:
      name: sortBy
      in: query
      schema:
        $ref: '#/components/schemas/ProductsSortBy'
    ProductsProjectionQuery:
      name: projection
      in: query
      schema:
        $ref: '#/components/schemas/ProductsProjection'