Instock

Instock Inventory API

Inventory resource returns data on the current quantity of article(s) that your organization has uploaded, use it to track articles that are low in stock or out-of-stock and require replenishment in scope of particular site.

GitHub OpenAPI
Business capability
Inventory Management BC-530

Operations 4

GET /{site_id}/inventory List all articles inventory #
POST /{site_id}/inventory Retrieve multiple articles inventory #
PUT /{site_id}/inventory Adjust article inventory #
GET /{site_id}/inventory/{article_id} Retrieve article inventory #

Documentation

📖
Documentation
https://instock.com/en/docs/
📖
APIReference
https://instock.com/en/docs/api/
📖
GettingStarted
https://instock.com/en/docs/getting-started/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/instock/refs/heads/main/openapi/instock-inventory-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/instock-inventory-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

instock-inventory-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  contact:
    name: Instock
    email: info@instock.com
    url: https://instock.com
  license:
    name: Instock
    url: https://instock.com
  title: Instock API reference Inventory API
  version: 0.1.0
  description: '# Overview

    This reference is a comprehensive guide to understanding of Instock API and is aimed to

    help developers to integrate their Host system with Instock Cloud (Incloud).'
servers:
- url: https://api.instock.com/v1
security:
- bearerAuth: []
tags:
- name: Inventory
  description: 'Inventory resource returns data on the current quantity of article(s) that your organization has uploaded, use it to track

    articles that are low in stock or out-of-stock and require replenishment in scope of particular site.'
paths:
  /{site_id}/inventory:
    get:
      tags:
      - Inventory
      summary: List all articles inventory
      description: 'Returns a paginated list of inventory for all articles within specific site.


        **Note**: The response excludes articles where `free`, `reserved` and `registered` quantity values are all equal to `0`.

        However, those articles are still in Incloud and their inventory data can be retrieved individually

        via article inventory retrieval.'
      operationId: getAllInventory
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: 'curl -X GET ''https://api.instock.com/v1/{SITE_ID}/inventory?start_cursor={START_CURSOR}&page_size={PAGE_SIZE}'' \

          -H ''Authorization: Bearer {ACCESS_TOKEN}''

          '
      parameters:
      - $ref: '#/components/parameters/instockCorrelationID'
      - $ref: '#/components/parameters/siteID'
      - $ref: '#/components/parameters/startCursor'
      - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: Successful operation.
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inventoryQtyAllArticles'
              examples:
                Inventory of all articles:
                  $ref: '#/components/examples/severalInventoryArticles'
        '400':
          description: Bad request
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Bad request:
                  value:
                    code: bad_request
                    message: Request body/path/query params cannot be validated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Not found
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Site doesn't exist:
                  value:
                    code: resource_not_found
                    message: site_id doesn't exist.
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Inventory
      summary: Retrieve multiple articles inventory
      description: Returns inventory for multiple articles by article IDs within specific site.
      operationId: retrieveMultipleArticlesInventory
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X POST 'https://api.instock.com/v1/{SITE_ID}/inventory' \\\n-H 'Authorization: Bearer {ACCESS_TOKEN}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"article_ids\": [\n    \"016000124790\",\n    \"HOOD_M_SIZE_2A1T\"\n  ]\n}'\n"
      parameters:
      - $ref: '#/components/parameters/instockCorrelationID'
      - $ref: '#/components/parameters/siteID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/inventoryQtyMultipleArticlesRequest'
            examples:
              Retrieve multiple articles inventory:
                $ref: '#/components/examples/fetchMultipleInventoryArticlesRequest'
      responses:
        '200':
          description: Successful operation.
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inventoryQtyMultipleArticlesResponse'
              examples:
                Inventory of multiple articles:
                  $ref: '#/components/examples/fetchMultipleInventoryArticlesResponse'
        '400':
          description: Bad request
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Bad request:
                  value:
                    code: bad_request
                    message: Request body/path/query params cannot be validated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Not found
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Article doesn't exist:
                  value:
                    code: resource_not_found
                    message: article_id doesn't exist.
    put:
      tags:
      - Inventory
      summary: Adjust article inventory
      description: '> **Important**: this a debug endpoint, use it during integration with Incloud or during debugging.


        Adjusts inventory of one or more articles for virtual site.


        **Note**: `"qty": 0` will remove inventory (free stock) of a given article.'
      operationId: adjustArticleInventory
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X PUT 'https://api.instock.com/v1/{SITE_ID}/inventory' \\\n-H 'Authorization: Bearer {ACCESS_TOKEN}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"adjustments\": [\n    {\n      \"article_id\": \"016000124790\",\n      \"qty\": 300\n    }\n  ]\n}'\n"
      parameters:
      - $ref: '#/components/parameters/instockCorrelationID'
      - $ref: '#/components/parameters/siteID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/adjustInventory'
            examples:
              Adjust inventory of a single article:
                $ref: '#/components/examples/singleArticleAdjustment'
              Adjust inventory of multiple articles:
                $ref: '#/components/examples/multipleArticleAdjustment'
      responses:
        '200':
          description: Successful operation.
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                type: string
              examples:
                response:
                  value: ''
        '400':
          description: Bad request
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Bad request:
                  value:
                    code: bad_request
                    message: Request body/path/query params cannot be validated.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /{site_id}/inventory/{article_id}:
    get:
      tags:
      - Inventory
      summary: Retrieve article inventory
      description: Returns inventory for a single article by article ID within specific site.
      operationId: getInventoryArticleId
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: 'curl -X GET ''https://api.instock.com/v1/{SITE_ID}/inventory/{ARTICLE_ID}'' \

          -H ''Authorization: Bearer {ACCESS_TOKEN}''

          '
      parameters:
      - $ref: '#/components/parameters/instockCorrelationID'
      - $ref: '#/components/parameters/siteID'
      - $ref: '#/components/parameters/articleID'
      responses:
        '200':
          description: Successful operation.
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inventoryQtyArticleId'
              examples:
                Inventory of a single article:
                  $ref: '#/components/examples/singleInventoryArticle'
                Inventory of an out-of-stock article:
                  $ref: '#/components/examples/singleInventoryArticleOos'
        '400':
          description: Bad request
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Bad request:
                  value:
                    code: bad_request
                    message: Request body/path/query params cannot be validated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Not found
          headers:
            Instock-Response-ID:
              $ref: '#/components/headers/instockRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Site doesn't exist:
                  value:
                    code: resource_not_found
                    message: site_id doesn't exist.
                Article doesn't exist:
                  value:
                    code: resource_not_found
                    message: article_id doesn't exist.
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    startCursor:
      name: start_cursor
      in: query
      required: false
      description: "Cursor returned from a previous response, \nused to request the next page of the results. \n"
      schema:
        type: string
        example: fe2cc560-036c-44cd-90e8-294d5a74cebc
        default: ''
    instockCorrelationID:
      name: Instock-Correlation-ID
      description: Optional header ID to track and analyze requests and behaviors across your Host system.
      in: header
      required: false
      schema:
        type: string
    articleID:
      name: article_id
      in: path
      description: ID of an article. Unique in scope of your organization(s).
      required: true
      schema:
        $ref: '#/components/schemas/articleId'
      example: 016000487727
    siteID:
      name: site_id
      in: path
      required: true
      description: ID of Instock site. Globally unique.
      schema:
        $ref: '#/components/schemas/siteId'
      example: 1.1.0-1
    pageSize:
      name: page_size
      in: query
      required: false
      description: "The number of articles returned in response. \nDefault (minimum) value is 10, maximum value is 1000.\n"
      schema:
        type: integer
        format: int64
        example: 10
        default: 10
        maximum: 1000
  schemas:
    inventoryRetrievalTimestamp:
      type: string
      format: date-time
      description: Timestamp of inventory retrieval from database [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).
      example: '2023-01-01T00:00:00Z'
    adjustInventory:
      type: object
      properties:
        adjustments:
          type: array
          items:
            $ref: '#/components/schemas/adjustArticleInventory'
    inventoryQtyMultipleArticlesRequest:
      type: object
      properties:
        article_ids:
          description: List of articles.
          type: array
          items:
            $ref: '#/components/schemas/articleId'
          maxItems: 1000
    siteId:
      type: string
      description: ID of Instock site. Globally unique.
    articleId:
      type: string
      description: ID of an article. Unique in scope of your organization(s).
      pattern: ^[a-zA-Z0-9_+.]+$
    inventoryQtyMultipleArticlesResponse:
      type: object
      properties:
        org_id:
          type: string
          description: ID of an organization. Globally unique.
        site_id:
          type: string
          description: ID of Instock site. Globally unique.
        timestamp:
          $ref: '#/components/schemas/inventoryRetrievalTimestamp'
        articles:
          description: List of articles.
          type: array
          items:
            type: object
            properties:
              article_id:
                $ref: '#/components/schemas/articleId'
              qty:
                type: object
                properties:
                  reserved:
                    type: integer
                    format: int64
                  free:
                    type: integer
                    format: int64
                  registered:
                    type: integer
                    format: int64
                description: 'Quantity of articles in a specific state:

                  * `reserved` - quantity of articles that is reserved for fulfillment order that is in progress

                  * `free` - quantity of articles that is available in stock

                  * `registered` - sum of all `requested` quantities of a specific article in the lines of all orders that are in status `registered`

                  '
    adjustArticleInventory:
      type: object
      properties:
        article_id:
          $ref: '#/components/schemas/articleId'
        qty:
          type: integer
          format: int64
          description: 'Quantity of a specific article to adjust.

            This value will be used to increment the inventory count.

            `"qty": 0` will remove inventory (free stock) of a given article.

            '
    Error:
      type: object
      properties:
        code:
          description: Code that identifies the reason of an error.
          type: string
        message:
          description: Description of an error.
          type: string
    inventoryQtyAllArticles:
      type: object
      properties:
        has_more:
          type: boolean
          description: 'If `true`, `next_cursor` to access next part of the list.

            If `false`, response includes the end of the list.

            '
        next_cursor:
          type: string
          description: "Only available when `has_more` is `true`.\nUsed to retrieve the next page of results by \npassing the value as the `start_cursor` parameter \nto the same endpoint.\n"
        org_id:
          type: string
          description: ID of an organization. Globally unique.
        site_id:
          type: string
          description: ID of Instock site. Globally unique.
        timestamp:
          $ref: '#/components/schemas/inventoryRetrievalTimestamp'
        articles:
          description: List of articles.
          type: array
          items:
            type: object
            properties:
              article_id:
                $ref: '#/components/schemas/articleId'
              qty:
                type: object
                properties:
                  reserved:
                    type: integer
                    format: int64
                  free:
                    type: integer
                    format: int64
                  registered:
                    type: integer
                    format: int64
                description: 'Quantity of articles in a specific state:

                  * `reserved` - quantity of articles that is reserved for fulfillment order that is in progress

                  * `free` - quantity of articles that is available in stock

                  * `registered` - sum of all `requested` quantities of a specific article in the lines of all orders that are in status `registered`

                  '
    inventoryQtyArticleId:
      type: object
      properties:
        org_id:
          type: string
          description: ID of an organization. Globally unique.
        site_id:
          type: string
          description: ID of Instock site. Globally unique.
        timestamp:
          $ref: '#/components/schemas/inventoryRetrievalTimestamp'
        article_id:
          $ref: '#/components/schemas/articleId'
        qty:
          type: object
          properties:
            reserved:
              type: integer
              format: int64
            free:
              type: integer
              format: int64
            registered:
              type: integer
              format: int64
          description: 'Quantity of articles in a specific state:

            * `reserved` - quantity of articles that is reserved for fulfillment order that is in progress

            * `free` - quantity of articles that is available in stock

            * `registered` - sum of all `requested` quantities of a specific article in the lines of all orders that are in status `registered`

            '
  examples:
    severalInventoryArticles:
      value:
        has_more: false
        next_cursor: ''
        org_id: org_id_001
        site_id: 1.1.0-1
        timestamp: '2022-06-06T12:37:00Z'
        articles:
        - article_id: '1003000031678'
          qty:
            reserved: 0
            free: 100
            registered: 0
        - article_id: '116000487727'
          qty:
            reserved: 25
            free: 50
            registered: 10
        - article_id: '116000275270'
          qty:
            reserved: 10
            free: 100
            registered: 0
    fetchMultipleInventoryArticlesResponse:
      value:
        org_id: org_id_001
        site_id: 1.1.0-1
        timestamp: '2022-06-06T12:37:00Z'
        articles:
        - article_id: '1003000031678'
          qty:
            reserved: 0
            free: 100
            registered: 0
        - article_id: '116000487727'
          qty:
            reserved: 25
            free: 50
            registered: 10
        - article_id: '116000275270'
          qty:
            reserved: 10
            free: 100
            registered: 0
    singleArticleAdjustment:
      value:
        adjustments:
        - article_id: '116000487727'
          qty: 15
    fetchMultipleInventoryArticlesRequest:
      value:
        article_ids:
        - '1003000031678'
        - '116000487727'
        - '116000275270'
    singleInventoryArticleOos:
      value:
        org_id: org_id_001
        site_id: 1.1.0-1
        timestamp: '2022-06-06T13:37:00Z'
        article_id: '116000487727'
        qty:
          reserved: 0
          free: 0
          registered: 0
    singleInventoryArticle:
      value:
        org_id: org_id_001
        site_id: 1.1.0-1
        timestamp: '2022-06-06T12:38:00Z'
        article_id: '1003000031678'
        qty:
          reserved: 10
          free: 100
          registered: 0
    multipleArticleAdjustment:
      value:
        adjustments:
        - article_id: '116000487727'
          qty: 10
        - article_id: '116000275270'
          qty: 20
  responses:
    Forbidden:
      description: Forbidden
      headers:
        Instock-Response-ID:
          $ref: '#/components/headers/instockRequestID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: forbidden
            message: API key doesn't have permissions to perform the request.
    InternalServerError:
      description: Internal server error
      headers:
        Instock-Response-ID:
          $ref: '#/components/headers/instockRequestID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: internal_server_error
            message: Unexpected error occurred.
    Unauthorized:
      description: Unauthorized
      headers:
        Instock-Response-ID:
          $ref: '#/components/headers/instockRequestID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: unauthorized
            message: API key is not valid.
  headers:
    instockRequestID:
      description: Auto-generated ID in the response headers to reference a specific request, useful for debugging or seeking support.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      type: http
      scheme: bearer