Item.Upsert

Adds or fully replaces products in the register's shared catalog and returns local IDs for carts. All integrations of this register can access these products.

Pass the integration Bearer token in the HTTP header. See API authentication.

Input parameters

Name	Data type	Required	Description
items	array	Required	1–150 products; external_id values must be unique within the batch
items[].item_id	int64	Without external_id	Existing local product ID, greater than 0; may identify any register product
items[].external_id	string	Without item_id	Shared key across the register, 1–100 characters; surrounding whitespace removed
items[].name	string	Required	Product name, 1–60 characters
items[].barcode	string	Optional	Up to 21 characters; default empty
items[].icps	string	Required	Exactly 17 digits
items[].price	int64	Required	Unit price in tiyin, >= 0
items[].vat_value	int64	Required	VAT percent ×100; must exist in the register
items[].unit_kkm_code	int64	Optional	Existing unit code; default 1
items[].package_code	string	Optional	Package code for this ICPS; first available package used when omitted
items[].owner_type	int32	Required	0 — resale; 1 — production; 2 — service

Supply item_id, external_id or both. Without item_id, a new external key creates a product; an existing key updates the same product across all integration tokens. item_id updates an existing product, including locally created products; unknown IDs return 701001. Both identifiers must match. A new key may be assigned to a product without one; an assigned key cannot be silently replaced. To update without changing its key, send only item_id.

An old external key linked to several products returns 701003 without item_id. Supply both fields to select its shared product explicitly. Other products remain available by their own item_id. Matching ICPS codes do not merge products. Updating one product twice in a batch, even through different identifiers, is rejected. Send all required product details again; this is not a partial update. Updating a deleted product restores it.

ICPS, package, allowed VAT and its effective period use the receipt validation rules. The supplied name is preserved instead of being replaced with the ICPS name; only surrounding whitespace is removed. The catalog can normalize the barcode; VAT 600 is imposed when required. Marking and payment restrictions come from ICPS. An individual marking code is not required for catalog creation. The batch is atomic: no products are saved if any product fails.

Request example

Authorization: Bearer <integration-token>
Content-Type: application/json;charset=utf-8

{
    "jsonrpc": "2.0",
    "method": "Item.Upsert",
    "params": {
        "items": [
            {
                "external_id": "SKU-001",
                "name": "Тестовый товар",
                "barcode": "4780000000000",
                "icps": "00000000000000000",
                "price": 10000,
                "vat_value": 0,
                "owner_type": 0
            }
        ]
    },
    "id": 1
}

Update an existing product by local ID (send all required details again):

{
    "jsonrpc": "2.0",
    "method": "Item.Upsert",
    "params": {
        "items": [
            {
                "item_id": 101,
                "name": "Test product 250 g",
                "barcode": "4780000000000",
                "icps": "00000000000000000",
                "price": 12000,
                "vat_value": 0,
                "owner_type": 0
            }
        ]
    },
    "id": 2
}

Output parameters

Name	Data type	Description
items	array	Products
items[].external_id	string	Shared external key; empty if updated only by item_id without an assigned key
items[].item_id	int64	Local product ID for Cart.Add
items[].created	boolean	Whether a new product was created
items[].name	string	Product name
items[].barcode	string	Barcode; empty if absent
items[].price	int64	Unit price in tiyin
items[].vat_value	int64	VAT in hundredths of a percent; -1 means no VAT
items[].icps	string	ICPS code
items[].package_code	string or null	Package code; null if absent

Result.items contains one entry per input product, in input order: external_id, item_id, created (new product), and effective name, barcode, price, vat_value, icps, package_code (null if none). Examples below use fictitious identifiers; substitute valid product data.

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "items": [
            {
                "external_id": "SKU-001",
                "item_id": 101,
                "created": true,
                "name": "Тестовый товар",
                "barcode": "4780000000000",
                "price": 10000,
                "vat_value": 0,
                "icps": "00000000000000000",
                "package_code": null
            }
        ]
    },
    "ok": true,
    "id": 1
}

Errors: common errors, 701001 for an unknown item_id, 701003 for product fields, conflicting identifiers or VAT/unit/package, 705511 for missing ICPS information. Catalog service failures return their corresponding error code without saving products.