# Exporting stock balances and prices to a website via the API

URL: https://bimpsoft.com/en/help/developers/sync-stock-and-prices/
Updated: 2026-11-06

> For stock balances, use GET /org2/inventory/api-readList/cursor (full export by warehouse) and the inventory_balance webhook (near real-time changes). For prices, use nomenclature/api-readPrices with a period or priceList/api-readPrice. Available stock in the response is quantity minus reserved.

## What we are building

Regular updating of stock and product prices on a website, marketplace or in your CRM. The scheme: a full export once at the start, then change events, and once a day a reconciliation that fixes anything missed. All calls are made with the company token in the `access-token` header ([Getting started with the API](https://bimpsoft.com/en/help/developers/api-getting-started/)). Mapping website products to Bimp products is by external ID or article number: [Catalog sync](https://bimpsoft.com/en/help/developers/sync-catalog/).

## Which methods to call and in what order

| Step | Method | Why |
|---|---|---|
| 1 | [`organization/api-readList`](/en/help/developers/api-reference/organization/#api-read-list) and [`warehouse/api-readList`](/en/help/developers/api-reference/warehouse/#api-read-list) | Get `orgId` and `warehouseId` for stock requests |
| 2 | [`inventory/api-readList/cursor`](/en/help/developers/api-reference/inventory/) | Full export of [warehouse](https://bimpsoft.com/en/help/inventory/warehouses/) stock with cursor pagination |
| 3 | [`webhook/api-upsert`](/en/help/developers/api-reference/webhook/#api-upsert) (`inventory_balance`) | Receive stock changes as events, without polling |
| 4 | `inventory/api-read/{productHex}/stock` | Spot-check product availability before placing an order |
| 5 | [`priceList/api-readList`](/en/help/developers/api-reference/price-list/#api-read-list) | Find the price list you need (the `main` field marks the main one) |
| 6 | [`nomenclature/api-readPrices`](/en/help/developers/api-reference/nomenclature/#api-read-prices) | Product prices in price lists, including changes for a period |
| 7 | `priceList/api-readPrice` | All prices of one price list |

## How to export stock balances

The `GET /org2/inventory/api-readList/cursor` method returns warehouse stock in portions. Required query parameters: `orgId` (organization) and `warehouseId` (warehouse). `limit` is from 1 to 200 (default 50), and `lastId` is the cursor for the next portion.

```bash
curl -G https://app.bimpsoft.com/org2/inventory/api-readList/cursor \
  -H "access-token: $COMPANY_TOKEN" \
  --data-urlencode "orgId=<organization-uuid>" \
  --data-urlencode "warehouseId=<warehouse-uuid>" \
  --data-urlencode "limit=200"
```

Response:

```json
{
  "success": true,
  "data": {
    "items": [
      { "productId": "<product-uuid>", "barcode": "4820000000012", "quantity": 25, "reserved": 5, "available": 20 }
    ],
    "next_cursor": "<last-product-uuid>"
  }
}
```

To get the next portion, pass `next_cursor` in the `lastId` parameter. Stop when the portion is empty.

Stock fields:

| Field | What it means |
|---|---|
| `quantity` | Physical stock in the warehouse |
| `reserved` | Reserved quantity, see [Reserving goods](https://bimpsoft.com/en/help/sales/reserves/) |
| `available` | Available quantity: `quantity` minus `reserved` |
| `barcode` | Barcode; may be empty |
| `batchId` | Batch, only with `byBatches=true` (then add `lastBatchId` for the cursor, the value from `next_cursor_batch_id`) |

There is also a page-number version, `GET /org2/inventory/api-readList` with the `page` and `pageSize` parameters (up to 100) and sorting by `sortBy` (`productId`, `quantity`, `reserved`, `available`) and `sortDirection`. For a full export the cursor is more reliable: it does not "drift" if data changes during reading.

Get stock for several warehouses with separate requests for each `warehouseId`. An alternative with one request for several warehouses is `nomenclature/api-readStocks` (filters `warehouseUuid[]`, `nomenclatureUuid[]`, `offset`/`count` pagination); the response has `stock`, `reserve`, `leftover`, `minimumLeftover`, `maximumLeftover` and `primeCost`.

## How to receive stock changes through a webhook

The `inventory_balance` webhook sends an event when stock changes: sale, receipt, [write-off](https://bimpsoft.com/en/help/inventory/write-off/), transfer. Create it with the `webhook/api-upsert` method:

```bash
curl -X POST https://app.bimpsoft.com/org2/webhook/api-upsert \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventKind": "inventory_balance",
    "name": "Залишки для сайту",
    "url": "https://shop.example.com/hooks/bimp-stock",
    "enabled": true,
    "warehouseIds": [ { "name": "Основний склад", "GUID": "<warehouse-uuid>" } ]
  }'
```

In `warehouseIds`, specify the warehouses whose changes you care about. The event contains the product `id`, `barcode`, `sku`, `name`, `total_physical`, `total_reserved`, `total_available`, the `stock_details` array by warehouse (`storage_id`, `physical`, `reserved`, `available`) and `timestamp`. Send `total_available` or `available` of the needed warehouse to the website. For receiver details, see [Webhooks](https://bimpsoft.com/en/help/developers/webhooks/).

Events may arrive faster than you can process them. Compare `timestamp` and do not overwrite a newer value with an older one.

## How to export prices

Prices are stored in price lists ([Price lists](https://bimpsoft.com/en/help/pricing/price-lists/)). The `nomenclature/api-readPrices` method returns, for each product, prices by price list. The required parameter is `periodable`: a point in time or a period `[start, end)`. The value `null` or `[null, null]` means the entire period, `[null, "date"]` means up to a date, and `["date", null]` means from a date.

```bash
curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-readPrices \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "priceListUuids": ["<price-list-uuid>"],
    "periodable": ["2026-11-05T00:00:00.000Z", "2026-11-06T00:00:00.000Z"],
    "pagination": { "offset": 0, "count": 100 }
  }'
```

For each product, the response has `uuid`, `name` and a `priceLists` array: `uuid`, `name`, `price` and `currency` (`uuid`, `iso`, `symbol`).

For a full export of one price list, use `priceList/api-readPrice` with `priceListUuid`: the response is a list of products with a `prices` array (`amount`, `date`, `currency`). For the list of price lists, use `priceList/api-readList`; the field `main: true` marks the main one.

To handle currencies correctly, compare `currency.iso` in the response with your website's currency: rates are not converted automatically. How prices in foreign currency are maintained is covered in Price lists.

## How not to overload the API

- **Limit:** 15 requests per second from one IP, then a queue of 30 requests, and the rest get a 429 error. For `inventory` methods, the 429 response has `retryAfter`, the time until you should retry ([Limits](https://bimpsoft.com/en/help/developers/api-limits/)).
- **Portion size.** For `inventory/api-readList/cursor` use `limit=200`, and for POST methods with `pagination` use `count=100` (the maximum).
- **Webhooks instead of frequent polling.** Do a full export at startup and once a day at night, and live on events during the day.
- **Do not poll product by product.** The `inventory/api-read/{productHex}/stock` method is suitable for a check before placing an order, but not for bulk updates.

## Common errors

**Stock on the website is higher than what is available in Bimp.** Cause: you send `quantity` instead of `available` and ignore the reserve. Solution: send `available`.

**A 422 response to a stock request.** Cause: the required `orgId` or `warehouseId` was not passed, or they are not UUIDs. Solution: get the values from `organization/api-readList` and `warehouse/api-readList`.

**A 404 response to `inventory/api-read/{productHex}/stock`.** Cause: the product is not in this warehouse's stock or the identifier is wrong. The path accepts `productHex` in the form `0x…` (16-32 hexadecimal characters) or a UUID.

**Prices on the website do not match Bimp.** Cause: the wrong price list or currency was exported. Solution: check `priceLists[].uuid` and `currency.iso`.

**The webhook stopped arriving.** Check that the webhook is enabled (`enabled`) and that your URL responds with a success code; the requirements are described in Webhooks.

## FAQ

**Which stock should I send to the website: physical or available?**

Available (available) is physical stock minus reserves. This is what can be sold. The available field is returned by the inventory/api-readList methods and the inventory_balance webhook (total_available).

**How often should I poll stock?**

It is better to subscribe to the inventory_balance webhook and do a full reconciliation once a day. If there is no webhook, poll every 10-30 minutes, without exceeding 15 requests per second per IP.

**How do I get stock broken down by batch?**

Pass the byBatches=true parameter to inventory/api-readList or api-readList/cursor. Each row will contain batchId.

**How do I export prices with changes for a period?**

Call nomenclature/api-readPrices with periodable as [start, end) and, if needed, priceListUuids.