Syncing the product catalog via the API

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). For products in the interface, see Products and services.

Which methods to call and in what order

Step	Method	Why
1	nomenclature-group/api-readList	Get the group tree (uuid, name, parentuuid)
2	unitsOfMeasurment/api-readList	Get units of measure for creating products
3	nomenclature/api-readList	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:

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:

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.

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.

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.

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.

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 method:

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.

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):

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.

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.