# Syncing the product catalog via the API

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

> To sync the catalog, map the products of the two systems with nomenclature/api-saveExternalId, and create new products with nomenclature/api-create (optionally with the integration field right away). Receive product changes from Bimp through the product_upsert webhook or through nomenclature/api-readList with the created and updated filters.

## What we are building

A consistent product catalog between Bimp and your system: an online store, marketplace or PIM. Bimp is usually the source of truth for products, prices and stock; the website can be the source of descriptions and photos. Below is how to map products, load new ones and keep up with changes. The company token is passed in the `access-token` header ([Getting started with the API](https://bimpsoft.com/en/help/developers/api-getting-started/)). For products in the interface, see [Products and services](https://bimpsoft.com/en/help/products/products-and-services/).

## Which methods to call and in what order

| Step | Method | Why |
|---|---|---|
| 1 | [`nomenclature-group/api-readList`](/en/help/developers/api-reference/nomenclature-group/#api-read-list) | Get the group tree (`uuid`, `name`, `parentuuid`) |
| 2 | [`unitsOfMeasurment/api-readList`](/en/help/developers/api-reference/units-of-measurment/#api-read-list) | Get units of measure for creating products |
| 3 | [`nomenclature/api-readList`](/en/help/developers/api-reference/nomenclature/#api-read-list) | Initial catalog read with pagination |
| 4 | `nomenclature/api-readWithoutExternalId` | Find Bimp products not yet mapped to your system |
| 5 | `nomenclature/api-saveExternalId` | Map a Bimp product to an ID in your system |
| 6 | `nomenclature/api-readByExternalId` | Find a Bimp product by an ID in your system |
| 7 | `nomenclature/api-create` | Create a product (or modification) that does not exist |
| 8 | `nomenclature/api-update` | Update the name, article number, description, dimensions and so on |
| 9 | `nomenclature-group/api-create` | Create a missing group |

## How to map existing products

The initial mapping is done once. There are two approaches.

**By article number or barcode.** Read the Bimp catalog in batches of 100 and compare it with your database by `article` or `sku` (Bimp stores the barcode in the `sku` field). For each matched pair, call `nomenclature/api-saveExternalId`:

```bash
curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-saveExternalId \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "nomenclatureUuid": "<product-uuid>", "source": "myshop", "externalId": "SKU-48215" }'
```

**Through the list without a mapping.** `nomenclature/api-readWithoutExternalId` with `source` returns only products that are not yet in your system, which is convenient for step-by-step work:

```bash
curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-readWithoutExternalId \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "pagination": { "offset": 0, "count": 100 }, "source": "myshop" }'
```

The response is an array of `nomenclatureUuid` and `name`. After each mapping the product disappears from the list, so the loop ends when the list is empty.

## How to create a product

The `nomenclature/api-create` method takes the required `name` and `unitOfMeasurementUuid`, and the product type is set by `type`: `goods` (product) or `service` (service). Additionally: `fullName`, `article`, `sku`, `group`, `supplier`, `description`, `comment`, `measurements` (`height`, `length`, `width` in centimeters, `weight` in kilograms, all four fields together) and `VATaccounted`.

```bash
curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "goods",
    "name": "Кавоварка Aroma 2000",
    "article": "AR-2000",
    "sku": "4820000000012",
    "unitOfMeasurementUuid": "<unit-uuid>",
    "group": "<group-uuid>",
    "description": "Крапельна кавоварка, 1,2 л",
    "measurements": { "height": 30, "length": 20, "width": 15, "weight": 2.4 },
    "integration": { "system": "<integration-system-uuid>", "externalId": "48215" }
  }'
```

Response: `{ "success": true, "data": { "uuid": "<product-uuid>" } }`.

The `integration` field is optional: it links the product to an object in the external system right away, and by this link the product can be found in `nomenclature/api-readList` (the `integration` filter with `system` and `externalId`). The `system` value is the UUID of the integration system, not the `source` string; for simplicity, use the pair "`api-create` + `api-saveExternalId`".

### Modifications

A modification is a separate product with a link to a parent product. To create one, add `isModification: true` and `parent`, the uuid of the parent product. Read a parent's modifications through `nomenclature/api-readList` with the `parentUuid` parameter. In the response, `isParent` marks a parent product, and `isModification` and `parent` mark a modification. For modifications in the interface, see [Modifications](https://bimpsoft.com/en/help/products/variants/).

### Groups

A group is created by `nomenclature-group/api-create` (`name`, optionally `description` and `parentuuid`). The list of groups is returned by `api-readList` (the `uuid` field in the request is an optional filter by a list of uuids). Build the tree by `parentuuid`: [Product groups](https://bimpsoft.com/en/help/products/product-groups/).

## How to update a product

`nomenclature/api-update` takes `uuid` and only the fields that change: `name`, `fullName`, `article`, `sku`, `group`, `unitOfMeasurementUuid`, `description`, `comment`, `picture`, `measurements`, `VATaccounted`.

```bash
curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-update \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "uuid": "<product-uuid>", "description": "Крапельна кавоварка, 1,2 л, чорна" }'
```

`api-update` does not accept `type`, so the product type cannot be changed after creation.

## How to receive catalog changes

**The `product_upsert` webhook.** The event arrives when a product is created or changed. Create a webhook with the [`webhook/api-upsert`](/en/help/developers/api-reference/webhook/#api-upsert) method:

```bash
curl -X POST https://app.bimpsoft.com/org2/webhook/api-upsert \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventKind": "product_upsert",
    "name": "Товари для сайту",
    "url": "https://shop.example.com/hooks/bimp-product",
    "enabled": true
  }'
```

The event contains `product`: `uuid`, `name`, `article`, `sku`, `description`, `picture`, `isModification`, `measurements` (`weight`, `length`, `width`, `height`) and `timestamp`. For a modification, a `parent` block with the parent product data is added. For the format, see [Webhooks](https://bimpsoft.com/en/help/developers/webhooks/).

**Time-based polling.** The `created` and `updated` filters in `nomenclature/api-readList` accept a pair of dates `["from", "to"]` in ISO 8601 (either bound can be replaced with `null`):

```bash
curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-readList \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pagination": { "offset": 0, "count": 100 },
    "updated": [["2026-11-05T00:00:00.000Z", null]]
  }'
```

Remember the start time of the previous request, and next time pass it as the lower bound.

## How to avoid duplicate products

1. Before `api-create`, call `nomenclature/api-readByExternalId` with your `source` and `externalId`. A `null` response means the product does not exist.
2. To search by your name or article number, use the `article`, `name`, `nameContains` filters in `api-readList` rather than comparing on your side.
3. Right after creation, call `api-saveExternalId` (or pass `integration` at creation).
4. For a broader view of mappings, use `api-readExternalIdsList` (filters `source`, `nomenclatureGuid`). To delete a mapping, use `api-deleteExternalId`: if you do not pass `source`, all mappings of this product are deleted.

The external ID rules are shared by all resources: [External IDs](https://bimpsoft.com/en/help/developers/api-external-ids/).

## Common errors

**A validation error when creating a product.** Cause: `name`, `unitOfMeasurementUuid` or `type` was not passed, or `measurements` is not fully filled (all four values are required together). Solution: pass all required fields.

**A modification was created as a separate product.** Cause: `isModification: true` was not passed together with `parent`. Solution: change the request structure; an already created product cannot be turned into a modification with `api-update`.

**After deleting a mapping, the product appeared in `readWithoutExternalId` again.** This is expected behavior: the method shows all products without a mapping for the specified `source`.

**A large catalog export is interrupted.** Cause: the limit of 15 requests per second. Solution: batches of 100, a pause on 429, see [Limits](https://bimpsoft.com/en/help/developers/api-limits/).

## FAQ

**How do I find Bimp products that are not yet in my system?**

Call nomenclature/api-readWithoutExternalId with your source: the method returns products with no mapping to that system.

**How do I create a product via the API and link it to my ID right away?**

In nomenclature/api-create pass an integration object with the system and externalId fields. The alternative is to create the product and call api-saveExternalId.

**How do I pass a modification (size, color)?**

Create a modification with isModification=true and parent set to the uuid of the parent product. In readList the parent product has isParent=true, and the modification has isModification=true and parent.

**How do I get only changed products?**

Use the updated filter (a pair of dates [from, to]) or created in nomenclature/api-readList. Or subscribe to the product_upsert webhook.