Exporting stock balances and prices to a website via the API

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). Mapping website products to Bimp products is by external ID or article number: Catalog sync.

Which methods to call and in what order

Step	Method	Why
1	organization/api-readList and warehouse/api-readList	Get orgId and warehouseId for stock requests
2	inventory/api-readList/cursor	Full export of warehouse stock with cursor pagination
3	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	Find the price list you need (the main field marks the main one)
6	nomenclature/api-readPrices	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.

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:

{
  "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
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, transfer. Create it with the webhook/api-upsert method:

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.

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). 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.

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).
• 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.