Inventory via the API: stock posting, movements, turnovers, products
On this page
- What we are building
- How to post goods via the API
- How to update, find and cancel a stock posting
- How to transfer goods between warehouses and read a transfer
- How to read a write-off
- How to follow the chain “Assembly → Production order → Stock transfer”
- How to get stock movements for a period
- How to get turnovers and balances for a period
- Who sees movements, turnovers and cost price
- How to create a warehouse via the API
- How to create many products in one request
- How to move goods between companies of an account
- Common errors
- FAQ
With the Bimp API you can post goods to a warehouse (inventoryPosting/api-create), read stock movements for a period (inventory/api-readMovements) and turnovers with opening and closing balances (inventory/api-readTurnovers), create a warehouse (warehouse/api-create) and load up to 500 products in one request (nomenclature/api-createBatch). The API has no transfer between companies of one account: it is a write-off in one company and a stock posting in the other.
What we are building
An inventory integration: a WMS, a production system or an accounting program posts goods to Bimp, creates warehouses and products, and reads movements and turnovers for a period back. Below are the API methods for these tasks. All requests are POST to https://app.bimpsoft.com/org2/... with the company token in the access-token header (Getting started with the API). The document logic in the interface is described in Stock posting and Write-off.
| Task | Method |
|---|---|
| Create, update, read a stock posting | inventoryPosting: api-create, api-update, api-read, api-readList, api-cancel |
Transfers between warehouses (with products in api-read) | movementOfInventories: api-create, api-update, api-read, api-readList, api-cancel |
| Stock movements for a period | inventory/api-readMovements |
| Turnovers and balances for a period | inventory/api-readTurnovers |
| Create, update, read a warehouse | warehouse: api-create, api-update, api-read, api-readList |
| Create many products in one request | nomenclature/api-createBatch |
| Read a write-off with its operation type and write-off account | writeOffOfInventories/api-read |
| Find write-offs by organization and period | writeOffOfInventories/api-readList |
| Find assemblies by organization and period | production-assembly/api-readList |
| Find the transfers created from a production order | production-order/api-read, the movements field |
| Accounts for Cost price transfer lines and the write-off account | accounts/api-readList |
Current balances for a website are read by another method, inventory/api-readList, see Exporting stock balances and prices to a website.
How to post goods via the API
inventoryPosting/api-create creates a Stock posting document, which receives goods without a supplier: surpluses after a stock count, returns, entering balances manually. Required fields: organization, incomeItem (income item) and the products array. Each line requires nomenclature, warehouse, quantity and price; project and lineOfBusiness are optional. The header can contain number, date, comment, responsible.
curl -X POST https://app.bimpsoft.com/org2/inventoryPosting/api-create \
-H "access-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"organization": "<organization-uuid>",
"incomeItem": "<income-item-uuid>",
"date": "2026-11-10T09:00:00",
"comment": "Surplus from the stock count on 10.11",
"products": [
{ "nomenclature": "<product-uuid>", "warehouse": "<warehouse-uuid>", "quantity": 12, "price": 140 },
{ "nomenclature": "<product-2-uuid>", "warehouse": "<warehouse-uuid>", "quantity": 3, "price": 860.5 }
]
}'
The response contains the uuid of the created document. The warehouse is set in each line, so one stock posting can put goods into several warehouses. price is the unit price: api-read returns it as the line amount divided by the quantity, rounded to two digits. quantity must be greater than zero: a line with zero or a negative value returns a 4xx error, and the document is not created.
Reference values come from organization/api-readList, incomeItems/api-readList, warehouse/api-readList, project/api-readList and lineOfBusiness/api-readList.
How to update, find and cancel a stock posting
inventoryPosting/api-update takes the document uuid and the same fields as api-create; organization, incomeItem and products are required here too. The method sends the whole document: the products lines you pass replace all existing lines rather than merging with them. So send the whole document, with all its lines. The same goes for date, responsible, number and comment: if you omit them, the document date becomes the current one and the responsible person becomes the API user. Read the document with api-read first and pass these fields from it.
inventoryPosting/api-read returns the header and the products lines with the same fields by uuid. inventoryPosting/api-readList returns total and rows (uuid, number, date, comment, archived, sum, organization, incomeItem, responsible) with pagination (offset, count up to 100). Filters go in the filters object:
| Filter | Value |
|---|---|
date | Period ["from", "to"] in ISO 8601; the upper bound can be null |
organization, incomeItems, responsible | Arrays of uuids |
number, comment | String |
sum | Amount range [min, max], either bound can be null |
showArchived | true also shows archived documents |
inventoryPosting/api-cancel with a uuid cancels the document.
How to transfer goods between warehouses and read a transfer
movementOfInventories/api-create creates a Stock transfer document between warehouses of one company. Required fields: author, fromWarehouse (the sending warehouse), toWarehouse (the receiving warehouse) and operationType: 0 “To warehouse”, 1 “In transit”, 2 “Cost price”. Optional: status (0 completed, 1 request), number, name, date, comment, organization, project, lineOfBusiness, responsibleSender, responsibleReceiver, baseDocument, processing, counterparty and the products array.
Each products line is nomenclature and count; unitOfMeasurement, invoice (the Customer order the goods are transferred for), project, lineOfBusiness, expenseItem and account are optional. The last two are needed for the Cost price operation type, see below.
curl -X POST https://app.bimpsoft.com/org2/movementOfInventories/api-create \
-H "access-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"author": "<employee-uuid>",
"fromWarehouse": "<warehouse-kyiv-uuid>",
"toWarehouse": "<warehouse-lviv-uuid>",
"operationType": 0,
"products": [
{ "nomenclature": "<product-uuid>", "count": 15 },
{ "nomenclature": "<product-2-uuid>", "count": 4 }
]
}'
Cost price transfers. The operationType: 2 type moves goods not for storage but for cost accumulation: the cost is collected on an expense item and an expense account and later distributed by a Cost allocation document. So every products line must contain two fields:
| Field | Meaning | Where to get it |
|---|---|---|
expenseItem | Expense item | expenseItems/api-readList |
account | Expense account, usually 23 “Work in progress” or 25 | accounts/api-readList with the filter { "codes": ["23", "25"] } |
accounts/api-readList returns an array of { uuid, code, name } sorted by code: the same list of accounts as in the “Expense account” field of a transfer in the app. Without codes the method returns all accounts.
curl -X POST https://app.bimpsoft.com/org2/movementOfInventories/api-create \
-H "access-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"author": "<employee-uuid>",
"fromWarehouse": "<warehouse-kyiv-uuid>",
"toWarehouse": "<warehouse-production-uuid>",
"operationType": 2,
"products": [
{
"nomenclature": "<product-uuid>",
"count": 5,
"expenseItem": "<expense-item-uuid>",
"account": "<account-23-uuid>"
}
]
}'
If any line lacks expenseItem or account, the document is not created and the API returns 400 with the line number. For operationType 0 and 1 these fields are optional. api-update checks the same way: if products is passed without operationType, the lines are checked against the operation type already set in the document.
movementOfInventories/api-update takes the uuid and only the fields that change, including products. If products is passed, it replaces all lines of the document; an empty array products: [] clears the lines; if products is omitted, the lines stay as they were. There is no method to delete a single line: read the document with api-read, remove the line and pass the rest.
Products in api-read. movementOfInventories/api-read returns, by uuid, the document header (number, date, comment, archived, operationType, status, fromWarehouse, toWarehouse, author, organization, processing, counterparty) and the products array in the order of the document lines:
| Field | Meaning |
|---|---|
uuid, name | The product; for a modification, the uuid and name of the modification |
count | Quantity |
unitOfMeasurement | Unit of measurement |
invoice | Customer order |
project, lineOfBusiness | Project, line of business |
expenseItem, account | Expense item and expense account of the line (for Cost price) |
Optional line fields are returned only when they are filled in the document. Note that in a request the product is passed in the nomenclature field, while in the api-read response it is the uuid field. A document without products returns products: [].
movementOfInventories/api-readList returns rows and total without products. The filters object accepts date (period ["from", "to"]), fromWarehouse, toWarehouse, organization, author (arrays of { "uuid": "..." } objects), operationType and status (arrays of { "uuid": <number> }), name, comment and showArchived. movementOfInventories/api-cancel with a uuid cancels the transfer. In stock movements, a transfer gives two lines of type movementOfInventories: an expense at the sending warehouse and a receipt at the receiving one.
How to read a write-off
writeOffOfInventories/api-read returns a Write-off document by uuid: the header (number, date, comment, organization, author, responsible, expenseItem, invoiceForCustomerPayment, sum) and the products lines (nomenclature, warehouse, quantity, sum, project, lineOfBusiness). The response also has two header fields:
| Field | Meaning |
|---|---|
operationType | The document’s “Operation type”, a numeric code; null if the field is empty |
writeOffAccount | The “Write-off account”: the uuid of an account from accounts/api-readList; null if the field is empty |
writeOffOfInventories/api-readList returns an object: total is the number of documents matching the filters, and rows are the documents of the requested page, newest first (uuid, number, date, comment, organization, author, expenseItem, sum). The list does not include products; call api-read for them. The date filter is a [begin, end) period: the beginning is included, the end is not; the end can be null.
How to follow the chain “Assembly → Production order → Stock transfer”
Production documents reference each other, so from the first document you can find the rest:
production-assembly/api-readreturns an Assembly with theproductionOrderfield, the uuid of the Production order.production-order/api-readreturns the order with themovementsfield, an array of the uuids of the stock transfers created from this order, newest first. If there are no transfers, the array is empty.movementOfInventories/api-readreturns each transfer with its products.
curl -X POST https://app.bimpsoft.com/org2/production-order/api-read \
-H "access-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "uuid": "<production-order-uuid>" }'
Part of the response:
{
"success": true,
"data": {
"uuid": "<production-order-uuid>",
"number": "9",
"movements": ["<movement-uuid>"]
}
}
movements lists the transfers whose “Order” field points to this production order: the document is filled in this way when a transfer is created based on the order. A canceled transfer stays in the list; a transfer marked for deletion does not.
The assembly list production-assembly/api-readList filters documents in the filters object: organization is an array of organization uuids, date is a [begin, end) period, and the end can be null.
curl -X POST https://app.bimpsoft.com/org2/production-assembly/api-readList \
-H "access-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"pagination": { "offset": 0, "count": 100 },
"filters": {
"organization": ["<organization-uuid>"],
"date": ["2026-10-01T00:00:00Z", "2026-11-01T00:00:00Z"]
}
}'
How to get stock movements for a period
inventory/api-readMovements returns the stock movement lines for a period: every receipt and every expense for every document, warehouse and product. period and pagination are required.
curl -X POST https://app.bimpsoft.com/org2/inventory/api-readMovements \
-H "access-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"period": ["2026-10-01T00:00:00Z", "2026-11-01T00:00:00Z"],
"warehouseUuids": ["<warehouse-uuid>"],
"documentTypes": ["purchaseInvoice", "salesInvoice", "writeOffOfInventories"],
"pagination": { "offset": 0, "count": 100 }
}'
periodis[begin, end): the beginning is included, the end is not. For October, pass2026-10-01and2026-11-01.warehouseUuids,nomenclatureUuidsare optional filters. The product filter includes the product’s modifications.documentTypeslimits the movements to these document types:purchaseInvoice,enteringOpeningBalances,inventoryPosting,receivingForSale,productionAssembly,productionDisassembly,productionTask,salesInvoice,cashRegisterReceipt,refundFromCustomer,writeOffOfInventories,putUnderAccounting,refundSupplier,movementOfInventories,transferForSale,reportForSale,extraExpenses,pieceworkSalary,expensesDistribution.
The response is an array ordered by date. One line is one document, warehouse, product and direction of movement:
| Field | Meaning |
|---|---|
date | Date of the movement (UTC) |
document | uuid, number and type of the document |
warehouse | uuid and name of the warehouse |
nomenclature | uuid, name and parent: the parent product for a modification, otherwise null |
quantity | Quantity: positive is a receipt, negative is an expense |
cost | Amount at cost price with the same sign as quantity, rounded to 2 digits |
A transfer between warehouses gives two lines: an expense at the sending warehouse and a receipt at the receiving one. Read pages until the response is shorter than count.
How to get turnovers and balances for a period
inventory/api-readTurnovers calculates, for every warehouse and product pair, the opening balance, the turnovers and the closing balance for a period. The figures match the Stock Movement report. dateFrom, dateTo (format YYYY-MM-DD, both dates included) and pagination are required; the warehouseUuids and nomenclatureUuids filters work as in movements.
curl -X POST https://app.bimpsoft.com/org2/inventory/api-readTurnovers \
-H "access-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"dateFrom": "2026-10-01",
"dateTo": "2026-10-31",
"pagination": { "offset": 0, "count": 100 }
}'
Each line contains warehouse, nomenclature and two blocks with the same fields: quantity (in quantity) and cost (at cost price):
| Field | What it includes |
|---|---|
opening | Balance at the start of dateFrom |
receipt | Receipts: goods receipts, opening balances, stock postings, customer returns, receiving for sale, production |
sale | Sales: delivery notes, receipts, sales reports |
writeOff | Write-offs: write-offs, production consumption, returns to supplier, putting under accounting |
transfer | Net transfers between warehouses and transfers for sale: negative at the sender, positive at the receiver |
closing | Balance at the end of dateTo = opening + receipt − sale − writeOff + transfer |
The response contains only warehouses with a balance or a movement in the period.
Who sees movements, turnovers and cost price
Both inventory/api-readMovements and inventory/api-readTurnovers require the API user to have the right to generate the Stock Movement report. Only the warehouses the user has access to are returned (Restricting an employee to specific warehouses). If the user has no access to the cost price of goods, the cost field comes back as null, while quantities are still returned.
How to create a warehouse via the API
warehouse/api-create requires only name. Optional fields:
| Field | Meaning |
|---|---|
main | Main warehouse |
active, archived | Active, archived |
publicWarehouse | Public warehouse |
type | Warehouse type (number): 2 is a warehouse group (a folder in the hierarchy, not a storage place), any other value is a regular warehouse. The field can be passed in api-create and api-update |
address, comment | Address, comment |
parent | Parent warehouse (uuid) for the hierarchy |
lineOfBusiness, priceList, cashRegister, responsible, counterparty | Line of business, price list, cash register, responsible person, counterparty (uuid) |
curl -X POST https://app.bimpsoft.com/org2/warehouse/api-create \
-H "access-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "Lviv warehouse", "address": "120 Horodotska St, Lviv", "parent": "<parent-warehouse-uuid>" }'
The response contains the uuid of the new warehouse. warehouse/api-update takes the uuid and only the fields that change (including name). warehouse/api-read returns all fields, plus code and predefined (a system warehouse), which cannot be set via the API. warehouse/api-readList returns uuid, name, main; the main: true filter leaves only the main warehouse. How warehouses work in the interface: Warehouses and stores.
How to create many products in one request
nomenclature/api-createBatch takes an items array of 1 to 500 products with the same fields as nomenclature/api-create. Product fields, modifications and the integration field are described in Catalog sync.
curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-createBatch \
-H "access-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"items": [
{ "type": "goods", "name": "Facade paint 10 l", "article": "FF-10", "unitOfMeasurementUuid": "<unit-uuid>" },
{ "type": "goods", "name": "Facade paint 5 l", "article": "FF-5", "unitOfMeasurementUuid": "<unit-uuid>" },
{ "type": "goods", "name": "Facade paint 10 l", "article": "FF-10B", "unitOfMeasurementUuid": "<unit-uuid>" }
]
}'
Each item is checked as in api-create. An item with an error is not created, but the rest are. The response:
{
"created": 2,
"failed": 1,
"results": [
{ "index": 0, "uuid": "<product-uuid>" },
{ "index": 1, "uuid": "<product-2-uuid>" },
{ "index": 2, "errors": [{ "message": "Nomenclature with this name: «Facade paint 10 l» is already in this request (item 0)." }] }
]
}
results follows the order of items, and index is the zero-based position in the array. Store the “your ID — uuid” pair for every successful item, fix the items with errors and send them again. Common item errors:
- The name already exists in the database or repeats in the request. Names are compared ignoring case and leading or trailing spaces; modifications are not checked.
- Integration was not found.
integration.systemcontains a uuid that does not exist in the company. - The plan’s product limit is used up. Items over the limit get a 402 (Payment Required) error; items within the limit are created in order.
A product_upsert webhook is sent for the created products, as with api-create (Webhooks).
How to move goods between companies of an account
The API does not support transfers between companies of one account: a Stock transfer document works only between warehouses of one company. A transfer between companies is done with two requests using the tokens of the two companies (/org2/auth/api-selectCompany for each):
- Sending company:
writeOffOfInventories/api-createwithorganization,expenseItem(an expense item fromexpenseItems/api-readList) andproducts, where each line requiresnomenclature,warehouse,quantity,projectandlineOfBusiness. - Receiving company:
inventoryPosting/api-createwith the same quantities. If the transfer must be recorded as a purchase from the other company, usepurchaseInvoice/api-create(Purchasing via the API).
# 1. Write-off in the sending company
curl -X POST https://app.bimpsoft.com/org2/writeOffOfInventories/api-create \
-H "access-token: $SENDER_COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"organization": "<sender-organization-uuid>",
"expenseItem": "<expense-item-uuid>",
"comment": "Transfer to the receiving company",
"products": [
{ "nomenclature": "<sender-product-uuid>", "warehouse": "<sender-warehouse-uuid>", "quantity": 20,
"project": "<sender-project-uuid>", "lineOfBusiness": "<sender-line-of-business-uuid>" }
]
}'
# 2. Stock posting in the receiving company
curl -X POST https://app.bimpsoft.com/org2/inventoryPosting/api-create \
-H "access-token: $RECEIVER_COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"organization": "<receiver-organization-uuid>",
"incomeItem": "<income-item-uuid>",
"comment": "Received from the sending company",
"products": [
{ "nomenclature": "<receiver-product-uuid>", "warehouse": "<receiver-warehouse-uuid>", "quantity": 20, "price": 140 }
]
}'
What to keep in mind:
- Each company has its own uuids. Products, warehouses and organizations of the receiving company have different uuids than those of the sender. Match products by article (the
articlefilter innomenclature/api-readList) or through external IDs with the sameexternalIdin both companies. - Stock posting price. The cost of the write-off can be taken from the sender’s
inventory/api-readMovements: the line of thewriteOffOfInventoriesdocument containscostandquantity, and the unit price iscost / quantity(both are negative). - Failure between the steps. If the write-off was created but the stock posting was not, repeat only the second step. To find unfinished transfers,
writeOffOfInventories/api-readListfilters write-offs byorganization(an array of uuids) anddate(period["from", "to"]);expenseItems,author,commentandsumare also available.
Common errors
The stock posting is not created, error in quantity. Cause: the quantity in a line is zero or negative. Solution: pass only positive quantities; use a write-off to reduce the balance.
Some warehouses are missing from movements or turnovers. Cause: the API user has access only to certain warehouses. Solution: extend the user’s access or use the token of a user who sees all warehouses.
cost is always null. Cause: the API user has no right to see the cost price. Solution: grant this right in the access settings.
Movements for a month miss the last day. Cause: the end of period in inventory/api-readMovements is not included. Solution: pass the first date of the next month. In inventory/api-readTurnovers, on the contrary, dateTo is included.
A Cost price transfer is not created, error 400 about expenseItem and account. Cause: with operationType: 2 a products line has no expense item or account. Solution: pass both fields in every line; take the account from accounts/api-readList.
Error 429. The request limit is exceeded, see API limits, pagination and errors.
FAQ
How do I post goods to a warehouse via the API without a purchasing document?
Call inventoryPosting/api-create: the organization, the income item and a products array where each line has nomenclature, warehouse, quantity (greater than zero) and price.
How do I get warehouse turnovers for a month, as in the Stock Movement report?
Call inventory/api-readTurnovers with dateFrom and dateTo in YYYY-MM-DD format (both dates included). For every warehouse and product pair the method returns the opening balance, receipt, sale, write-off, transfer and closing balance.
How many products can I create in one request?
Up to 500 with nomenclature/api-createBatch. Each item is checked as in api-create; an item with an error is not created but does not stop the others.
How do I move goods from one company of the account to another via the API?
There is no dedicated method. Make two requests with the tokens of the two companies: writeOffOfInventories/api-create in the sending company and inventoryPosting/api-create (or purchaseInvoice/api-create) in the receiving company.
How do I find the transfers created from a production order?
Call production-order/api-read: the movements field holds the uuids of the transfers created from this order, newest first. Read each transfer with movementOfInventories/api-read.
How do I create a transfer with the Cost price operation type via the API?
Pass operationType 2 to movementOfInventories/api-create, and in every products line pass expenseItem (an expense item from expenseItems/api-readList) and account (an expense account from accounts/api-readList, usually 23 or 25). If either field is missing in any line, the API returns a 400 error.