Exporting Bimp data for analytics via the API

What we are building

A regular export of Bimp data (sales, purchases, stock, prices, money) to your storage, dashboard or BI system. If ready-made reports in Looker Studio or Power BI are enough for you, use the BigQuery integration: BigQuery and Looker Studio, Power BI, BigQuery field reference. The API fits when you need to choose the set of fields, the schedule and the storage location yourself. The company token is passed in the access-token header (Getting started with the API).

Which methods to call and in what order

Step	Method	What we export
1	organization/api-readList, warehouse/api-readList, currency/api-readList, lineOfBusiness/api-readList, project/api-readList	Directories for decoding uuid values in reports
2	counterparty/api-readList, nomenclature/api-readList, nomenclature-group/api-readList	Counterparties, products, groups
3	invoiceForCustomerPayment/api-readList and invoiceForCustomerPayment/api-read	Customer orders: header and lines
4	salesInvoice/api-readList and salesInvoice/api-read	Shipments (Sales of goods and services)
5	customerPayment/api-readList	Customer payments
6	invoiceForSupplierPayment/api-readList, purchaseInvoice/api-readList, paymentToSupplier/api-readList	Purchasing: Supplier orders, Goods receipts, Supplier payments
7	inventory/api-readList/cursor and nomenclature/api-readLeftovers	Current stock and stock on a date, or its change over a period
8	nomenclature/api-readPrices	Prices by price list
9	financing-balance/api-readList	Money balances in accounts and cash desks
10	otherExpenses/api-readList, otherIncome/api-readList	Expenses and income

How to read large lists

All api-readList methods return data in portions. There are three pagination methods:

Method	Where it is used	Parameters
offset and count	Most POST methods	pagination: { "offset": 0, "count": 100 }, maximum count is 100
Cursor	inventory/api-readList/cursor	limit (up to 200), lastId; the response returns next_cursor
Page number	inventory/api-readList	page and pageSize (up to 100)

An example of batch-reading orders for a period:

curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-readList \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pagination": { "offset": 0, "count": 100 },
    "periodable": ["2026-10-01T00:00:00.000Z", "2026-10-31T23:59:59.999Z"]
  }'

Increase offset by count until the response is empty or shorter than count. Pass dates in UTC in ISO 8601 format with the letter Z.

To keep reading stable while data changes, sort the result in your storage by uuid and do an upsert (insert or update by uuid) rather than an append.

How to load only changes

Do a full export once, then switch to increments. Time filters depend on the resource:

Resource	Time filter	What it means
Customer orders	periodable	Period by document date
Customer orders	changeStatusTime	Period of status change
Shipments, receipts, payments	periodable	Period by document date
Products	created, updated	A pair of dates [from, to] (each can be replaced with null)
Prices	periodable in nomenclature/api-readPrices	Prices or their changes for a period [start, end)
Stock	periodable in nomenclature/api-readLeftovers	Stock on a date or change over a period
Counterparties	periodable	Period in counterparty/api-readList

The increment algorithm:

1. Before starting a run, record the current time T_start.
2. Read the data for the period [T_prev, T_start], where T_prev is the start time of the previous successful run. Take a small overlap (5-10 minutes) and remove repeats by uuid.
3. After successful completion, save T_start as T_prev.

A filter by document date does not see changes made to old documents. So once a day or once a week, re-read a deeper period (for example, the last 30 days) and overwrite it. Webhooks do not notify you about a document changed retroactively.

How to export stock and prices

• Current stock: GET /org2/inventory/api-readList/cursor with orgId, warehouseId and limit=200. With byBatches=true, each row is split by batch.
• Stock on a date or change over a period: nomenclature/api-readLeftovers with periodable (a pair [start, end]) and optional warehouseUuid and nomenclatureUuids. Response: uuid, name, leftover.
• Stock, reserves and cost price: nomenclature/api-readStocks: stock, reserve, leftover, minimumLeftover, maximumLeftover, primeCost (filters warehouseUuid[], nomenclatureUuid[]).
• Batches: nomenclature/api-readBatches (nomenclatureUuid): receipt date, quantity, price, supplier, expiration date (shelfLife).
• Prices: nomenclature/api-readPrices; for details and examples, see Exporting stock balances and prices.

For a daily stock snapshot, call the method at midnight Kyiv time and store the result with the snapshot date: this builds a stock history that current stock does not have.

How to organize the load

1. Directories first. Load organizations, warehouses, currencies, projects, lines of business, groups and products. Documents contain only the uuid of these objects.
2. Documents by period. Process month by month, so that after a failure you repeat only one period.
3. Detail. api-readList returns the document header (for customer orders, a products array with line uuids only). Lines with quantity, price and discount are returned by api-read by the document uuid. For large volumes, plan one api-read per document.
4. Speed. Do not exceed 15 requests per second from one IP, otherwise requests will go into a queue and the excess will get 429. Run parallel streams carefully and pause on 429 (Limits).
5. Token. The access token is valid for 1 hour: in long exports, refresh it with auth/api-refresh, and after the week ends, sign in again.
6. A separate user. For the export, create a separate API user with read-only rights to the sections you need: Roles and access rights.

Webhooks instead of polling

For operational metrics (stock, order statuses, product changes), subscribe to the inventory_balance, order_status and product_upsert webhooks and put the events into your storage: this is cheaper than frequent polling. Webhooks do not replace a full export: a missed event is not repeated, so do a reconciliation once a day. For the event format, see Webhooks.

Common errors

The report has long uuid values instead of names. Cause: in api-readList, the buyer, status, warehouse fields are returned as uuid. Solution: load the directories and join them in your storage.

Data was duplicated. Cause: an increment with overlap writes repeated rows. Solution: upsert by uuid.

Totals do not match Bimp reports. Cause: the export does not account for canceled documents, currency or VAT. Solution: reconcile with the relevant Bimp report for the same period; for a quick check, use Cash flow. The managerialAccounting and bookkeperAccounting flags in shipments and receipts separate managerial and bookkeeping accounting.

A 429 error during bulk reading. More than 15 requests per second were sent. Reduce parallelism and retry the request with a pause.

Data for early periods is empty. Cause: periodable was passed not in UTC or without Z. Solution: use the format 2026-10-01T00:00:00.000Z.