# Purchasing via the API: from a supplier order to payment

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

> The purchasing chain in the API mirrors the interface: Supplier order (invoiceForSupplierPayment/api-create), Goods receipt (purchaseInvoice/api-create referencing the order) and Supplier payment (paymentToSupplier/api-create with paymentDetails). Each document is created with a separate request and canceled with api-cancel.

## 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](https://bimpsoft.com/en/help/purchasing/purchase-order/), [Goods receipt](https://bimpsoft.com/en/help/purchasing/goods-receipt/) and [Supplier payment](https://bimpsoft.com/en/help/purchasing/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](https://bimpsoft.com/en/help/developers/api-getting-started/)).

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`](/en/help/developers/api-reference/counterparty/#api-read-list) (`types: ["isSupplier"]`) | Find the supplier; if missing, use `counterparty/api-insert` with `isSupplier: true` |
| 2 | [`contract/api-readList`](/en/help/developers/api-reference/contract/#api-read-list) | Find the contract with the supplier |
| 3 | [`organization/api-readList`](/en/help/developers/api-reference/organization/#api-read-list), [`warehouse/api-readList`](/en/help/developers/api-reference/warehouse/#api-read-list), [`project/api-readList`](/en/help/developers/api-reference/project/#api-read-list), [`lineOfBusiness/api-readList`](/en/help/developers/api-reference/line-of-business/#api-read-list) | Get reference values for the document |
| 4 | [`invoiceForSupplierPayment/api-create`](/en/help/developers/api-reference/invoice-for-supplier-payment/#api-create) | Create the Supplier order with lines |
| 5 | [`purchaseInvoice/api-create`](/en/help/developers/api-reference/purchase-invoice/#api-create) | Post the goods to the [warehouse](https://bimpsoft.com/en/help/inventory/warehouses/) based on the order |
| 6 | [`paymentToSupplier/api-create`](/en/help/developers/api-reference/payment-to-supplier/#api-create) | Pay the Supplier order |
| 7 | [`refundSupplier/api-create`](/en/help/developers/api-reference/refund-supplier/#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.

```bash
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](https://bimpsoft.com/en/help/sales/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](https://bimpsoft.com/en/help/purchasing/supplier-products/).

Supplier [order statuses](https://bimpsoft.com/en/help/sales/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](https://bimpsoft.com/en/help/basics/create-based-on/). 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`).

```bash
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`](/en/help/developers/api-reference/bank-accounts/#api-read-list) or [`cashRegistry/api-readList`](/en/help/developers/api-reference/cash-registry/#api-read-list).

```bash
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](https://bimpsoft.com/en/help/developers/payments-via-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](https://bimpsoft.com/en/help/purchasing/supplier-return/).

## 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](https://bimpsoft.com/en/help/developers/api-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](https://bimpsoft.com/en/help/developers/api-limits/).

## FAQ

**Which API method creates a Supplier order?**

invoiceForSupplierPayment/api-create. In Bimp, a Supplier order is the document "Invoice for supplier payment", and in the API it is called invoiceForSupplierPayment.

**Can I create a Goods receipt without a Supplier order?**

In the purchaseInvoice/api-create specification the invoiceForSupplierPayment field is required, so a Goods receipt is created based on a Supplier order. If there is no order, create it as the first step.

**How do I pay a Supplier order via the API?**

Call paymentToSupplier/api-create: specify the supplier, the currency and, in the paymentDetails array, the Supplier order and the payed amount.

**How do I cancel a purchasing document?**

Each document has an api-cancel method: purchaseInvoice, invoiceForSupplierPayment, paymentToSupplier, refundSupplier. Pass the document uuid.