# Syncing orders with an online store via the API

URL: https://bimpsoft.com/en/help/developers/sync-orders/
Updated: 2026-11-06

> To sync orders, create a Customer order in Bimp with invoiceForCustomerPayment/api-create and immediately store your system's order number with api-saveExternalId. Before creating, check api-readByExternalId so that no duplicates appear. Receive status changes from Bimp through the order_status webhook, and change the status from your side with api-updateStatus.

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

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`](/en/help/developers/api-reference/invoice-for-customer-payment/#api-read-by-external-id) | Check whether the order already exists in Bimp. If it does, go to the update (step 8) |
| 2 | [`counterparty/api-readByExternalId`](/en/help/developers/api-reference/counterparty/#api-read-by-external-id) | 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`](/en/help/developers/api-reference/nomenclature/#api-read-by-external-id) | Find the product for each line (see [catalog sync](https://bimpsoft.com/en/help/developers/sync-catalog/)) |
| 5 | `invoiceForCustomerPayment/api-create` | Create the Customer order with lines, warehouse, [price list](https://bimpsoft.com/en/help/pricing/price-lists/) and status |
| 6 | `invoiceForCustomerPayment/api-saveExternalId` | Record the mapping of the order `uuid` and the number in your system |
| 7 | [`customerPayment/api-create`](/en/help/developers/api-reference/customer-payment/#api-create) | Record the payment if the store accepted it online, see [Payments via the API](https://bimpsoft.com/en/help/developers/payments-via-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](https://bimpsoft.com/en/help/getting-started/projects-and-business-directions/), statuses) should be fetched once and stored in the integration configuration:

| What you need | Method |
|---|---|
| Organization | [`organization/api-readList`](/en/help/developers/api-reference/organization/#api-read-list) |
| [Warehouse](https://bimpsoft.com/en/help/inventory/warehouses/) | [`warehouse/api-readList`](/en/help/developers/api-reference/warehouse/#api-read-list) |
| Price list | [`priceList/api-readList`](/en/help/developers/api-reference/price-list/#api-read-list) |
| Line of business | [`lineOfBusiness/api-readList`](/en/help/developers/api-reference/line-of-business/#api-read-list) |
| Project | [`project/api-readList`](/en/help/developers/api-reference/project/#api-read-list) |
| Customer contract | [`contract/api-readList`](/en/help/developers/api-reference/contract/#api-read-list) |
| 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.

```bash
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:

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

Save the mapping right away:

```bash
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](https://bimpsoft.com/en/help/sales/reserves/).
- `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](https://bimpsoft.com/en/help/developers/api-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`](/en/help/developers/api-reference/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](https://bimpsoft.com/en/help/developers/webhooks/).

```bash
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`:

```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 },
    "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`:

```bash
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](https://bimpsoft.com/en/help/sales/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`](/en/help/developers/api-reference/sales-invoice/#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](https://bimpsoft.com/en/help/developers/api-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`](/en/help/developers/api-reference/inventory/)) and pass `reserve` in the line; for the causes, see [Goods are not reserved](https://bimpsoft.com/en/help/sales/reserve-troubleshooting/).

**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.

## FAQ

**How do I avoid creating a duplicate order if the request was repeated?**

Before creating, call invoiceForCustomerPayment/api-readByExternalId with your source and externalId. If an order is returned, you do not need to create a new one. After a successful api-create, call api-saveExternalId right away.

**How do I find out in the store that an order status changed in Bimp?**

Set up a webhook of the order_status type for the statuses you need. As a fallback, call invoiceForCustomerPayment/api-readList with the changeStatusTime filter every few minutes.

**Can I reserve goods when creating an order via the API?**

Yes, the products lines have a reserve field. The reserve is created within the available stock, as in the interface.

**How do I pass an order from Bimp to a store or CRM?**

Call invoiceForCustomerPayment/api-readWithoutExternalId with your source: the method returns orders that have no mapping in your system yet.