# Exporting Bimp data for analytics via the API

URL: https://bimpsoft.com/en/help/developers/bi-export-via-api/
Updated: 2026-11-06

> For your own analytics, read data with api-readList methods using offset/count pagination (up to 100 records) and a periodable period, and stock with the cursor-based inventory/api-readList/cursor. Do a full export once, then load only changes for a period. If you need ready-made tables for Looker Studio or Power BI, use the BigQuery integration.

## 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](https://bimpsoft.com/en/help/bi/bigquery-looker-studio/), [Power BI](https://bimpsoft.com/en/help/bi/power-bi/), [BigQuery field reference](https://bimpsoft.com/en/help/bi/bigquery-fields/). 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](https://bimpsoft.com/en/help/developers/api-getting-started/)).

## Which methods to call and in what order

| Step | Method | What we export |
|---|---|---|
| 1 | [`organization/api-readList`](/en/help/developers/api-reference/organization/#api-read-list), [`warehouse/api-readList`](/en/help/developers/api-reference/warehouse/#api-read-list), [`currency/api-readList`](/en/help/developers/api-reference/currency/#api-read-list), [`lineOfBusiness/api-readList`](/en/help/developers/api-reference/line-of-business/#api-read-list), [`project/api-readList`](/en/help/developers/api-reference/project/#api-read-list) | Directories for decoding `uuid` values in reports |
| 2 | [`counterparty/api-readList`](/en/help/developers/api-reference/counterparty/#api-read-list), [`nomenclature/api-readList`](/en/help/developers/api-reference/nomenclature/#api-read-list), [`nomenclature-group/api-readList`](/en/help/developers/api-reference/nomenclature-group/#api-read-list) | Counterparties, products, groups |
| 3 | [`invoiceForCustomerPayment/api-readList`](/en/help/developers/api-reference/invoice-for-customer-payment/#api-read-list) and `invoiceForCustomerPayment/api-read` | [Customer orders](https://bimpsoft.com/en/help/sales/customer-order/): header and lines |
| 4 | [`salesInvoice/api-readList`](/en/help/developers/api-reference/sales-invoice/#api-read-list) and `salesInvoice/api-read` | [Shipments](https://bimpsoft.com/en/help/sales/shipment/) (Sales of goods and services) |
| 5 | [`customerPayment/api-readList`](/en/help/developers/api-reference/customer-payment/#api-read-list) | Customer payments |
| 6 | [`invoiceForSupplierPayment/api-readList`](/en/help/developers/api-reference/invoice-for-supplier-payment/#api-read-list), [`purchaseInvoice/api-readList`](/en/help/developers/api-reference/purchase-invoice/#api-read-list), [`paymentToSupplier/api-readList`](/en/help/developers/api-reference/payment-to-supplier/#api-read-list) | Purchasing: [Supplier orders](https://bimpsoft.com/en/help/purchasing/purchase-order/), Goods receipts, Supplier payments |
| 7 | [`inventory/api-readList/cursor`](/en/help/developers/api-reference/inventory/) 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](https://bimpsoft.com/en/help/pricing/price-lists/) |
| 9 | [`financing-balance/api-readList`](/en/help/developers/api-reference/financing-balance/#api-read-list) | Money balances in accounts and cash desks |
| 10 | [`otherExpenses/api-readList`](/en/help/developers/api-reference/other-expenses/#api-read-list), [`otherIncome/api-readList`](/en/help/developers/api-reference/other-income/#api-read-list) | 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:

```bash
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](https://bimpsoft.com/en/help/sales/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](https://bimpsoft.com/en/help/developers/sync-stock-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](https://bimpsoft.com/en/help/getting-started/projects-and-business-directions/), 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](https://bimpsoft.com/en/help/developers/api-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](https://bimpsoft.com/en/help/access/roles/).

## Webhooks instead of polling

For operational metrics (stock, [order statuses](https://bimpsoft.com/en/help/sales/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](https://bimpsoft.com/en/help/developers/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](https://bimpsoft.com/en/help/reports/cash-flow-report/). 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`.

## FAQ

**How does exporting via the API differ from the BigQuery integration?**

The BigQuery integration automatically provides ready-made tables in Google storage for Looker Studio and Power BI. You need the API when you load data into your own storage or service and manage the set of fields and the schedule yourself.

**How do I load only new and changed data?**

Pass periods: periodable (for documents), changeStatusTime (customer orders), created and updated (products). Remember the time of the last successful run and use it as the start of the next period.

**How many records does one request return?**

For POST methods with pagination, up to 100 (count). The cursor-based inventory/api-readList/cursor returns up to 200 (limit).

**What are the request limits?**

15 requests per second from one IP, then a queue of 30 requests, and the rest get 429.