# Stock balances and kits: Bimp API methods

URL: https://bimpsoft.com/en/help/developers/api-reference/inventory/

Bimp API methods for the “Stock balances and kits” resource (`/org2/inventory/…`): 6 methods. Base URL: `https://app.bimpsoft.com`. All requests except login pass the company token in the `access-token` header — see [Getting started with the API](/en/help/developers/api-getting-started/).

| Method | What it does |
|---|---|
| [`GET /org2/inventory/api-readList`](#api-read-list) | Get inventory balances with pagination and dynamic sorting. Optimized for table interfaces with protection against deep pagination. |
| [`GET /org2/inventory/api-readList/cursor`](#api-read-list-cursor) | Get inventory balances using cursor-based pagination for infinite scroll. |
| [`GET /org2/inventory/api-read/{productHex}/stock`](#api-read-product-hex-stock) | Get current stock and reserves for a specific product by its hex identifier. Used for checking product availability before placing an order. |
| [`GET /org2/inventory/kits/api-readList`](#kits-api-read-list) | Get available kit quantities calculated from component stock. Uses offset pagination with max limit of 2000 kits. For larger datasets, use cursor pagination endpoint. |
| [`GET /org2/inventory/kits/api-readList/cursor`](#kits-api-read-list-cursor) | Get available kit quantities using cursor-based pagination. Optimized for large datasets (2000+ kits) with instant performance at any depth. Use this endpoint when the total number of kits exceeds 2000. |
| [`GET /org2/inventory/kits/{kitGuid}/components`](#kits-kit-guid-components) | Get kit components (table part) for a given kit by its GUID. Returns kit fields (name, code, description) and list of components with their quantities. |

## api-readList

`GET /org2/inventory/api-readList`

Get inventory balances with pagination and dynamic sorting. Optimized for table interfaces with protection against deep pagination.

**Request parameters (query/path)**

| Field | Type | Required | Description |
|---|---|---|---|
| `orgId` | string (uuid) | yes | A unique identifier for the Organization, obtainable from the /organization/api-readList request |
| `warehouseId` | string (uuid) | yes | A unique identifier for the Warehouse, obtainable from the /warehouse/api-readList request |
| `page` | integer |  | Page number |
| `pageSize` | integer |  | Number of items per page |
| `sortBy` | string ("productId") \| string ("quantity") \| string ("reserved") \| string ("available") |  | Field to sort by |
| `sortDirection` | string ("asc") \| string ("desc") |  | Sort direction |
| `byBatches` | boolean \| string ("true") \| string ("false") |  | When true, balances are split by batch. Each row includes batchId. |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `[].productId` | string (uuid) | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `[].barcode` | string | Product barcode. May be empty for products without barcode. |
| `[].article` | string \| null |  |
| `[].quantity` | number | Total quantity in stock |
| `[].reserved` | number | Reserved quantity |
| `[].available` | number | Available quantity (quantity - reserved) |
| `[].batchId` | string (uuid) \| null |  |

```bash
curl -X GET 'https://app.bimpsoft.com/org2/inventory/api-readList' \
  -H 'access-token: <company token>'
```

## api-readList/cursor

`GET /org2/inventory/api-readList/cursor`

Get inventory balances using cursor-based pagination for infinite scroll.

**Request parameters (query/path)**

| Field | Type | Required | Description |
|---|---|---|---|
| `orgId` | string (uuid) | yes | A unique identifier for the Organization, obtainable from the /organization/api-readList request |
| `warehouseId` | string (uuid) | yes | A unique identifier for the Warehouse, obtainable from the /warehouse/api-readList request |
| `lastId` | string (uuid) |  | ID of the last item from previous response (for cursor pagination) |
| `limit` | integer |  | Number of items to return |
| `byBatches` | boolean \| string ("true") \| string ("false") |  | When true, one row per product batch |
| `lastBatchId` | string (uuid) |  | When byBatches is enabled, pass the batchId from the last row of the previous page (next_cursor_batch_id). Omit if that row had batchId null. |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `items` | object[] |  |
| `items[].productId` | string (uuid) | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `items[].barcode` | string | Product barcode. May be empty for products without barcode. |
| `items[].article` | string \| null |  |
| `items[].quantity` | number | Total quantity in stock |
| `items[].reserved` | number | Reserved quantity |
| `items[].available` | number | Available quantity (quantity - reserved) |
| `items[].batchId` | string (uuid) \| null |  |
| `next_cursor` | string (uuid) | ID of the last item in the response (for next page) |
| `next_cursor_batch_id` | string (uuid) \| null |  |

```bash
curl -X GET 'https://app.bimpsoft.com/org2/inventory/api-readList/cursor' \
  -H 'access-token: <company token>'
```

## api-read/{productHex}/stock

`GET /org2/inventory/api-read/{productHex}/stock`

Get current stock and reserves for a specific product by its hex identifier. Used for checking product availability before placing an order.

**Request parameters (query/path)**

| Field | Type | Required | Description |
|---|---|---|---|
| `orgId` | string (uuid) | yes | A unique identifier for the Organization, obtainable from the /organization/api-readList request |
| `warehouseId` | string (uuid) | yes | A unique identifier for the Warehouse, obtainable from the /warehouse/api-readList request |
| `productHex` | string | yes | Product identifier in hex format (e.g., 0x8934A1B2C3D4E5F6) |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `product_hex` | string | Product identifier in hex format |
| `available_quantity` | number | Available quantity (quantity - reserved) |
| `reserved_quantity` | number | Reserved quantity |
| `last_updated` | string (date-time) | Last update timestamp |

```bash
curl -X GET 'https://app.bimpsoft.com/org2/inventory/api-read/{productHex}/stock' \
  -H 'access-token: <company token>'
```

## kits/api-readList

`GET /org2/inventory/kits/api-readList`

Get available kit quantities calculated from component stock. Uses offset pagination with max limit of 2000 kits. For larger datasets, use cursor pagination endpoint.

**Request parameters (query/path)**

| Field | Type | Required | Description |
|---|---|---|---|
| `orgId` | string (uuid) | yes | A unique identifier for the Organization, obtainable from the /organization/api-readList request |
| `warehouseStock` | string (uuid) | yes | A unique identifier for the Warehouse, obtainable from the /warehouse/api-readList request for stock |
| `warehouseReserve` | string (uuid) | yes | A unique identifier for the Warehouse, obtainable from the /warehouse/api-readList request for reserves |
| `page` | integer |  | Page number |
| `pageSize` | integer |  | Number of items per page |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `[].id` | string (uuid) | Kit unique identifier |
| `[].barcode` | string | Kit barcode. May be empty for kits without barcode. |
| `[].article` | string | Kit article (SKU). May be null for kits without article. |
| `[].quantity` | number | Available kit quantity calculated from component free stock |
| `[].physical` | number | Physical kit quantity calculated from component physical stock |

```bash
curl -X GET 'https://app.bimpsoft.com/org2/inventory/kits/api-readList' \
  -H 'access-token: <company token>'
```

## kits/api-readList/cursor

`GET /org2/inventory/kits/api-readList/cursor`

Get available kit quantities using cursor-based pagination. Optimized for large datasets (2000+ kits) with instant performance at any depth. Use this endpoint when the total number of kits exceeds 2000.

**Request parameters (query/path)**

| Field | Type | Required | Description |
|---|---|---|---|
| `orgId` | string (uuid) | yes | A unique identifier for the Organization, obtainable from the /organization/api-readList request |
| `warehouseStock` | string (uuid) | yes | A unique identifier for the Warehouse, obtainable from the /warehouse/api-readList request for stock |
| `warehouseReserve` | string (uuid) | yes | A unique identifier for the Warehouse, obtainable from the /warehouse/api-readList request for reserves |
| `lastId` | string (uuid) |  | ID of the last kit from previous response (for cursor pagination) |
| `limit` | integer |  | Number of items to return |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `items` | object[] |  |
| `items[].id` | string (uuid) | Kit unique identifier |
| `items[].barcode` | string | Kit barcode. May be empty for kits without barcode. |
| `items[].article` | string | Kit article (SKU). May be null for kits without article. |
| `items[].quantity` | number | Available kit quantity calculated from component free stock |
| `items[].physical` | number | Physical kit quantity calculated from component physical stock |
| `next_cursor` | string (uuid) | ID of the last item in the response (for next page) |

```bash
curl -X GET 'https://app.bimpsoft.com/org2/inventory/kits/api-readList/cursor' \
  -H 'access-token: <company token>'
```

## kits/{kitGuid}/components

`GET /org2/inventory/kits/{kitGuid}/components`

Get kit components (table part) for a given kit by its GUID. Returns kit fields (name, code, description) and list of components with their quantities.

**Request parameters (query/path)**

| Field | Type | Required | Description |
|---|---|---|---|
| `kitGuid` | string (uuid) | yes | Kit unique identifier |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `kitGuid` | string (uuid) | Kit unique identifier |
| `kitFields` | object |  |
| `kitFields.name` | string | Kit name |
| `kitFields.code` | string | Kit code |
| `kitFields.description` | string | Kit description |
| `components` | object[] |  |
| `components[].componentGuid` | string (uuid) | Component unique identifier |
| `components[].quantity` | number | Quantity of component in the kit |

```bash
curl -X GET 'https://app.bimpsoft.com/org2/inventory/kits/{kitGuid}/components' \
  -H 'access-token: <company token>'
```

Interactive documentation with a test request option: [https://app.bimpsoft.com/docs](https://app.bimpsoft.com/docs). The OpenAPI specification is updated together with Bimp; this page is generated from it automatically.