Syncing orders with an online store via the API

What we are building

A one-way or two-way exchange of orders between Bimp and your system (online store, CRM, marketplace): new orders arrive in Bimp as a Customer order, and status and payment changes return to your system. All calls are made with the company token in the access-token header, see Getting started with the API.

The key idea: each order has a pair of identifiers. uuid is in Bimp, externalId is in your system. The pair is stored by the api-saveExternalId method under a source name (for example, myshop). You look up the order by this pair, not by document number.

Which methods to call and in what order

Step	Method	Why
1	invoiceForCustomerPayment/api-readByExternalId	Check whether the order already exists in Bimp. If it does, go to the update (step 8)
2	counterparty/api-readByExternalId	Find the customer by the customer ID in your system
3	counterparty/api-insert and counterparty/api-saveExternalId	If the customer does not exist, create it (isCustomer: true) and save the mapping
4	nomenclature/api-readByExternalId	Find the product for each line (see catalog sync)
5	invoiceForCustomerPayment/api-create	Create the Customer order with lines, warehouse, price list and status
6	invoiceForCustomerPayment/api-saveExternalId	Record the mapping of the order uuid and the number in your system
7	customerPayment/api-create	Record the payment if the store accepted it online, see Payments via the API
8	invoiceForCustomerPayment/api-updateStatus	Change the order status in Bimp on an event in your system
9	invoiceForCustomerPayment/api-cancel	Cancel the order if the customer refused

Reference values (organization, warehouse, price list, line of business, project, statuses) should be fetched once and stored in the integration configuration:

What you need	Method
Organization	organization/api-readList
Warehouse	warehouse/api-readList
Price list	priceList/api-readList
Line of business	lineOfBusiness/api-readList
Project	project/api-readList
Customer contract	contract/api-readList
Order statuses	invoiceForCustomerPayment/api-readStatuses

How to create an order in Bimp

An order is created with a single invoiceForCustomerPayment/api-create request: the customer buyer is required, and the lines are passed as the products array, where nomenclature and count are required for each line.

curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer": "<buyer-uuid>",
    "organization": "<organization-uuid>",
    "contract": "<contract-uuid>",
    "warehouse": "<warehouse-uuid>",
    "priceList": "<price-list-uuid>",
    "status": "<status-uuid>",
    "date": "2026-11-06T10:15:00",
    "comment": "Замовлення myshop №10452",
    "deliveryMethod": "Нова Пошта",
    "deliveryAddress": "м. Київ, відділення №12",
    "recipient": "Іваненко Олена",
    "recipientPhone": "+380501112233",
    "products": [
      { "nomenclature": "<product-1-uuid>", "count": 2, "reserve": 2, "cost": 3100 },
      { "nomenclature": "<product-2-uuid>", "count": 1, "reserve": 1, "cost": 6200 }
    ]
  }'

The response contains the uuid of the new document:

{ "success": true, "data": { "uuid": "<order-uuid>" } }

Save the mapping right away:

curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-saveExternalId \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "orderUuid": "<order-uuid>", "source": "myshop", "externalId": "10452" }'

Field rules:

• date uses the format YYYY-MM-DDTHH:MM:SS. A Customer order cannot be dated in the future (see Customer order), so pass the current or a past moment.
• reserve is the quantity to reserve. The reserve is created within the available stock, as in the interface: Reserving goods.
• cost is the unit price.
• Bimp assigns the document number itself. You can pass your own number in docNumber, but you should not identify the order by it; use the external ID.

How to avoid duplicates

Duplicates appear when api-create has been executed but the response did not arrive, and your system repeated the call. Protection consists of three rules.

1. Read first. Before every api-create, call invoiceForCustomerPayment/api-readByExternalId with your source and externalId. A response of "data": null means the order does not exist.
2. Write the mapping immediately. api-saveExternalId is the next call after api-create, before any other logic.
3. Reconcile the data. Once a day, call api-readExternalIdsList with the source filter and compare it with your order database. The api-readWithoutExternalId method shows Bimp orders without a mapping, for example those created manually by managers.

The source name is case-insensitive, because the system normalizes it. Use one source per external system: do not mix a store and a marketplace. For details on mapping, see External IDs. The specification has no separate idempotency key for api-create, so the order “read, create, write” is mandatory.

How to receive status changes

The most reliable way is a webhook, with polling as a fallback.

The order_status webhook. Create a webhook with the webhook/api-upsert method with eventKind: "order_status", a url and a statusIds list of the statuses whose changes you care about. You can do the same in the interface: Company settings → Webhooks → Add. Bimp sends your URL a JSON with the order: order_id, status (uuid and name), sumPayed, sumShipped, TTN, buyer, warehouse and the products array. For the event format and receiver requirements, see Webhooks.

curl -X POST https://app.bimpsoft.com/org2/webhook/api-upsert \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventKind": "order_status",
    "name": "Статуси замовлень для myshop",
    "url": "https://shop.example.com/hooks/bimp-order-status",
    "enabled": true,
    "statusIds": [ { "name": "Оплачено", "GUID": "<status-uuid>" } ]
  }'

The webhook contains order_id, the order uuid in Bimp. To find the order in your system, call api-readExternalIdsList with orderUuid, or keep a reverse table on your side.

Fallback polling. If the webhook is unavailable or an event is lost, call invoiceForCustomerPayment/api-readList every 5-10 minutes with a period in changeStatusTime:

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 },
    "changeStatusTime": ["2026-11-06T09:00:00.000Z", "2026-11-06T09:10:00.000Z"]
  }'

For each order the response includes status, sumOrdered, sumPayed, sumShipped, quantityShipped and TTN. Pass dates in UTC in ISO 8601 format with the letter Z. Start each next window at the end of the previous one, with a small overlap, and remove repeats by uuid.

How to change the status from your side

The invoiceForCustomerPayment/api-updateStatus method accepts invoiceUuid and statusUuid:

curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-updateStatus \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invoiceUuid": "<order-uuid>", "statusUuid": "<status-uuid>" }'

The list of available statuses is returned by api-readStatuses (uuid, name, color). A status change can release the reserve or close the order, depending on the status settings, see Order statuses. Do not send a status in response to a webhook about the same status: this creates a loop.

How to change or cancel an order

To change an order, use invoiceForCustomerPayment/api-update: the uuid field is required, and you pass the rest as needed (comment, TTN, deliveryAddress, status, lines). To cancel, use api-cancel with uuid. Payments, shipments and returns are created as separate documents: for payment see Payments via the API, for shipment use salesInvoice/api-create with the invoiceForCustomerPayment link to the order.

Common errors

Two orders were created for one store order. Cause: api-create was repeated without checking the mapping. Solution: add the api-readByExternalId step before creating, and cancel the extra document with api-cancel.

Error 429. Cause: more than 15 requests per second arrived from one IP address, and the queue of 30 requests is full. Solution: limit the rate and retry the request with a delay. For details, see Limits.

The token no longer works. The access token lives for 1 hour, the refresh token for 1 week. Refresh the pair with auth/api-refresh, and after the week ends, sign in again via auth/api-login. Use a separate user for the API, not your main account: otherwise the user’s session in the system ends automatically.

The order was created without a reserve. Cause: there is not enough available stock or reserve was not passed. Solution: check the stock (inventory/api-readList) and pass reserve in the line; for the causes, see Goods are not reserved.

The product is not found by external ID. nomenclature/api-readByExternalId returns null. First sync the catalog, see Catalog sync, or find the product by article through nomenclature/api-readList (the article filter) and record the mapping.