Purchasing via the API: from a supplier order to payment

What we are building

Purchasing automation: a planning system, ERP or supplier integration creates Supplier orders in Bimp and records Goods receipts and payments. The document logic is described in Supplier order, Goods receipt and Supplier payment. Below are the same steps at the API level. The company token is passed in the access-token header (Getting started with the API).

Term mapping:

In the interface	In the API
Supplier order	invoiceForSupplierPayment
Goods receipt	purchaseInvoice
Supplier payment	paymentToSupplier
Return to supplier	refundSupplier

Which methods to call and in what order

Step	Method	Why
1	counterparty/api-readList (types: ["isSupplier"])	Find the supplier; if missing, use counterparty/api-insert with isSupplier: true
2	contract/api-readList	Find the contract with the supplier
3	organization/api-readList, warehouse/api-readList, project/api-readList, lineOfBusiness/api-readList	Get reference values for the document
4	invoiceForSupplierPayment/api-create	Create the Supplier order with lines
5	purchaseInvoice/api-create	Post the goods to the warehouse based on the order
6	paymentToSupplier/api-create	Pay the Supplier order
7	refundSupplier/api-create	If needed, return goods to the supplier
8	invoiceForSupplierPayment/api-readList, purchaseInvoice/api-readList, paymentToSupplier/api-readList	Monitor the state: what was ordered, received and paid

How to create a Supplier order

The invoiceForSupplierPayment/api-create method requires the supplier counterparty, the contract contract, the organization organization, the warehouse warehouse, the project project and the author author. Lines are passed as the products array; for each line nomenclature, quantity, price, lineOfBusiness, project and unitOfMeasurment are required.

curl -X POST https://app.bimpsoft.com/org2/invoiceForSupplierPayment/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "counterparty": "<supplier-uuid>",
    "contract": "<contract-uuid>",
    "organization": "<organization-uuid>",
    "warehouse": "<warehouse-uuid>",
    "project": "<project-uuid>",
    "author": "<employee-uuid>",
    "date": "2026-11-06T09:00:00",
    "automaticPaymentsPlanning": true,
    "products": [
      {
        "nomenclature": "<product-uuid>",
        "quantity": 100,
        "price": 85.5,
        "unitOfMeasurment": "<unit-uuid>",
        "lineOfBusiness": "<line-of-business-uuid>",
        "project": "<project-uuid>"
      }
    ]
  }'

Response: { "success": true, "data": { "uuid": "<supplier-order-uuid>" } }. The automaticPaymentsPlanning: true flag adds the document to the payment calendar. In a line you can pass invoiceForCustomerPayment, the Customer order the goods are being purchased for (purchasing “to order”), and supplierNomenclature, the product name at the supplier. Name mapping is described in Supplier products.

Supplier order statuses are returned by invoiceForSupplierPayment/api-readStatuses.

How to post goods

purchaseInvoice/api-create creates a Goods receipt document based on a Supplier order. Required header fields: organization, responsible, counterparty, warehouse, contract, invoiceForSupplierPayment, the accounting flags VATaccounted, costWithoutVAT, bookkeperAccounting, managerialAccounting, taxAccounting, and the products array.

For each products line, the required fields are product, orderedCount (ordered), warehouseCount (actually received), cost, sum, VATsum, lineOfBusiness, project and invoiceForCustomerPayment (can be null).

curl -X POST https://app.bimpsoft.com/org2/purchaseInvoice/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": "<organization-uuid>",
    "responsible": "<employee-uuid>",
    "counterparty": "<supplier-uuid>",
    "warehouse": "<warehouse-uuid>",
    "contract": "<contract-uuid>",
    "invoiceForSupplierPayment": "<supplier-order-uuid>",
    "date": "2026-11-10T12:00:00",
    "VATaccounted": false,
    "costWithoutVAT": false,
    "bookkeperAccounting": true,
    "managerialAccounting": true,
    "taxAccounting": false,
    "products": [
      {
        "product": "<product-uuid>",
        "orderedCount": 100,
        "warehouseCount": 98,
        "cost": 85.5,
        "sum": 8379,
        "VATsum": 0,
        "lineOfBusiness": "<line-of-business-uuid>",
        "project": "<project-uuid>",
        "invoiceForCustomerPayment": null
      }
    ]
  }'

Here 98 of 100 ordered units were received: the difference orderedCount − warehouseCount is shown in the document as a short delivery. After saving, the goods increase the stock in the warehouse warehouse, and the cost price is calculated according to the accounting rules, see Goods receipt. To change a document, use purchaseInvoice/api-update.

How to pay a supplier

paymentToSupplier/api-create requires counterparty and currency. The amount and purpose are set by the paymentDetails array: each element has invoiceForSupplierPayment (the Supplier order) and payed (the payment amount). The cash desk or bank account is passed in the paymentEntity field; its value is taken from bankAccounts/api-readList or cashRegistry/api-readList.

curl -X POST https://app.bimpsoft.com/org2/paymentToSupplier/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "counterparty": "<supplier-uuid>",
    "currency": "<currency-uuid>",
    "organization": "<organization-uuid>",
    "paymentEntity": "<bank-account-uuid>",
    "date": "2026-11-12T10:00:00",
    "comment": "Оплата за замовленням постачальнику",
    "paymentDetails": [
      { "invoiceForSupplierPayment": "<supplier-order-uuid>", "payed": 8379 }
    ]
  }'

One payment can close several orders: add more elements to paymentDetails. For foreign currency payments, each element has a calculationRate field (cross rate). For payment details, see Payments and expenses via the API.

How to return goods to a supplier

refundSupplier/api-create creates a return based on a Goods receipt: baseDocument is the uuid of the Goods receipt document, and products is an array with nomenclature, count, cost (and VAT if needed). You can also pass warehouse, responsible, date, comment. A refund of money from a supplier is a separate document, refundFromSupplier. For business rules, see Return to supplier.

How to avoid duplicates

The API specification has no external ID methods for purchasing documents (they exist for Customer orders, shipments, products and counterparties, see External IDs). So store the link to your system like this:

1. Pass your number in the document’s number field (Supplier order, Goods receipt) and keep a “your ID, Bimp uuid” pair in your own database.
2. After api-create, immediately record the received uuid in your database, before the next steps.
3. Before retrying creation after a failure, check api-readList by period (periodable for receipts and payments, the date filter for Supplier orders) and compare number or comment.
4. Map suppliers through counterparty/api-saveExternalId and products through nomenclature/api-saveExternalId.

Common errors

The Goods receipt is not created, a required field error. Cause: invoiceForSupplierPayment or one of the five accounting fields (VATaccounted, costWithoutVAT, bookkeperAccounting, managerialAccounting, taxAccounting) was not passed. Solution: pass all required header and line fields.

The payment was created, but the order is not considered paid. Cause: a different order is specified in paymentDetails, or the payed amount is less than the order amount. Solution: check invoiceForSupplierPayment and the amount; the remainder is visible in the response (remainder).

A document cannot be changed. If api-update rejects the changes, cancel the document with api-cancel and create a corrected one.

Error 429. More than 15 requests per second from an IP were sent, see Limits.