Cart.Add

Creates a separate saved cart with the supplied positions.

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

Input parameters

Name Data type Required Description
external_id string Required Cart creation key unique within the integration, 1–100 characters
items array Required 1–150 positions; cart limit is 150 total
items[].item_id int64 Required Local ID of any available register product, from Item.Get or Item.Upsert
items[].price int64 Optional Unit price in tiyin, >= 0; catalog price used if omitted
items[].quantity int64 Required Positive quantity ×1000; 1000 = one unit
items[].discount int64 Optional Position discount in tiyin, default 0; cannot exceed gross amount
items[].label string Optional Marking code; supplied codes are checked for format and barcode correspondence

Product details come from the saved catalog. A supplied price applies only to this position and does not update the catalog. Net amount is price × quantity / 1000, rounded to whole tiyin midpoint away from zero, minus discount. Discount applies to the entire position, not one unit. Each addition is a separate position. Existing positions retain their snapshot when the catalog changes.

A new external_id creates a new cart. Input cart_id is not supported; this method cannot append to an existing cart. Repeating the same external_id and parameters returns the original cart's current state without duplication, including after cancellation or checkout. Changed parameters with the same key return 703100. Preserve input values and position order for retries. Each request is atomic. The created cart ID remains in the response field cart_id.

Marking can be completed during future checkout. If supplied, quantity must be 1000 and the code must be unique within the cart. Final sale/payment/fiscal checks are not performed while saving a cart.

Request example

Authorization: Bearer <integration-token>
Content-Type: application/json;charset=utf-8
{
    "jsonrpc": "2.0",
    "method": "Cart.Add",
    "params": {
        "external_id": "ADD-001",
        "items": [
            {
                "item_id": 101,
                "quantity": 1000,
                "price": 11000,
                "discount": 1000
            }
        ]
    },
    "id": 2
}

Output parameters

Name Data type Description
cart_id string Local cart ID returned by Cart.Add
status string Cart state: open, process, finished or canceled
receipt_id string or null Completed receipt ID; null until completion
created_at string Creation time, register local time, YYYY-MM-DD HH:mm:ss
updated_at string Update time, register local time, YYYY-MM-DD HH:mm:ss
total int64 Cart net total after discounts, in tiyin
items array Cart positions
items[].item_id int64 Local product ID for Cart.Add
items[].name string Product name
items[].barcode string Barcode; empty if absent
items[].icps string ICPS code
items[].price int64 Unit price in tiyin
items[].quantity int64 Quantity in thousandths; 1000 means one unit
items[].discount int64 Discount for the entire position, in tiyin
items[].amount int64 Net amount after discount, in tiyin
items[].vat_value int64 VAT in hundredths of a percent; -1 means no VAT
items[].package_code string or null Package code; null if absent
items[].label string Unit marking code; empty if absent

Result: cart_id, status (open, process, finished or canceled), receipt_id (closed receipt ID, null until finished), created_at and updated_at (register local time, YYYY-MM-DD HH:mm:ss), total (net amount in tiyin), items. Each item has item_id, name, barcode, icps, price (unit price), quantity (×1000), discount, amount (after discount), vat_value, package_code and label. All monetary values are in tiyin.

New carts start in open. Cashier checkout changes status to process; completed fiscal checkout changes it to finished. Repeating the original request returns the current state.

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "cart_id": "0123456789abcdef0123456789abcdef",
        "status": "open",
        "receipt_id": null,
        "created_at": "2026-11-12 10:00:00",
        "updated_at": "2026-11-12 10:00:00",
        "total": 10000,
        "items": [
            {
                "item_id": 101,
                "name": "Тестовый товар",
                "barcode": "4780000000000",
                "icps": "00000000000000000",
                "price": 11000,
                "quantity": 1000,
                "discount": 1000,
                "amount": 10000,
                "vat_value": 0,
                "package_code": null,
                "label": ""
            }
        ]
    },
    "ok": true,
    "id": 2
}

Errors: common errors, 701001 for a missing/deleted product; 701003 for invalid parameters, including unsupported cart_id, price, quantity, discount, marking or position limit; 703100 for key conflict. Marking errors use the appropriate error code.