لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/basket-items.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Basket items

Manage product line items in orders: create, get, update, delete, search, aggregate. A basket item is a separate entity linked to an order by the orderId field. A single order may have several items — one per purchased product.

Bitrix24 API: sale.basketitem.* Scope: sale

Add item to basket

POST /v1/basket-items

Adds a product line item to an existing order. The item references a catalog product via productId, or is created as a virtual item when productId: 0. The request body is flat — no fields wrapper.

Request fields (body)

Parameter Type Required Description
ParameterorderId Typenumber Requiredyes DescriptionOrder identifier. Source: GET /v1/orders
ParameterproductId Typenumber Requiredyes DescriptionCatalog product identifier. Source: GET /v1/catalog-products. The value 0 creates a virtual item with no catalog link
Parametercurrency Typestring Requiredyes DescriptionItem currency. List: GET /v1/currencies
Parameterquantity Typenumber Requiredyes DescriptionQuantity
Parametername Typestring Requiredno DescriptionItem name. When productId > 0, it is taken from the product card — the passed value is not saved on creation. When productId: 0, it is saved as passed
Parameterprice Typenumber Requiredno DescriptionPrice per unit. For a virtual item, set manually. Passing price enables customPrice
ParameterbasePrice Typenumber Requiredno DescriptionBase price before discount. Defaults to price
ParameterdiscountPrice Typenumber Requiredno DescriptionDiscount amount per unit. Defaults to 0
ParametercustomPrice Typeboolean Requiredno DescriptionProtects the price from auto-recalculation when the product changes in the catalog. When price is passed, it is set to true. Defaults to false
ParametervatRate Typenumber Requiredno DescriptionVAT rate as a fraction of one. 0.20 = 20%, 0.10 = 10%, 0 — no VAT
ParametervatIncluded Typeboolean Requiredno DescriptionWhether VAT is included in the price. Defaults to true
Parameterweight Typenumber Requiredno DescriptionUnit weight in grams
ParametermeasureCode Typenumber Requiredno DescriptionMeasurement unit code. 796 — pcs, 163 — g, 006 — m
ParameterproductXmlId Typestring Requiredno DescriptionExternal product identifier. For a virtual item, set manually
ParametercatalogXmlId Typestring Requiredno DescriptionExternal catalog identifier. For a virtual item, set manually
ParameterxmlId Typestring Requiredno DescriptionExternal item identifier

Examples

The examples below create a virtual item with productId: 0, so name is saved as passed.

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/basket-items" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 1,
    "productId": 0,
    "currency": "USD",
    "quantity": 1,
    "name": "Gift wrapping"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/basket-items" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 1,
    "productId": 0,
    "currency": "USD",
    "quantity": 1,
    "name": "Gift wrapping"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/basket-items', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderId: 1,
    productId: 0,
    currency: 'USD',
    quantity: 1,
    name: 'Gift wrapping',
  }),
})

const { success, data } = await res.json()
console.log('Basket item ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/basket-items', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderId: 1,
    productId: 0,
    currency: 'USD',
    quantity: 1,
    name: 'Gift wrapping',
  }),
})

const { success, data } = await res.json()

A catalog item is created by passing the product's productId — name, price, and the measurement unit are pulled from its product card:

JSON 
{
  "orderId": 1,
  "productId": 119,
  "currency": "USD",
  "quantity": 2
}

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionFull object of the created item
Fielddata.id Typenumber DescriptionIdentifier of the created item
Fielddata.name Typestring DescriptionName. For a catalog product — from the product card, for a virtual item — as passed
Fielddata.price Typenumber DescriptionPrice per unit
Fielddata.customPrice Typeboolean Descriptiontrue if the price is set manually via price
Fielddata.productXmlId Typestring | null DescriptionExternal product identifier. null for a virtual item when no value is passed
Fielddata.catalogXmlId Typestring | null DescriptionExternal catalog identifier. null for a virtual item when no value is passed
Fielddata.dateInsert Typedatetime DescriptionCreation date

For the full field set, see GET /v1/basket-items/fields.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 1021,
    "orderId": 1,
    "productId": 0,
    "name": "Gift wrapping",
    "price": 0,
    "basePrice": 0,
    "discountPrice": 0,
    "customPrice": false,
    "currency": "USD",
    "quantity": 1,
    "sort": 100,
    "weight": null,
    "dimensions": null,
    "measureCode": null,
    "measureName": null,
    "canBuy": true,
    "vatRate": null,
    "vatIncluded": true,
    "xmlId": "bx_6a3e475a2d55c",
    "productXmlId": null,
    "catalogXmlId": null,
    "dateInsert": "2026-06-26T08:33:14.000Z",
    "dateUpdate": "2026-06-26T08:33:14.000Z"
  }
}

Error response example

422 — required fields not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Required fields: orderId, productId, currency, quantity"
  }
}

Errors

HTTP Code Description
HTTP422 CodeBITRIX_ERROR DescriptionRequired fields not passed — the message contains their list
HTTP422 CodeBITRIX_ERROR DescriptionNon-existent orderId or productId — the item is not saved
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the sale scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

For the full list of common API errors, see Errors.

Known specifics

A catalog product's name is taken from its card. When productId > 0, the fields name, productXmlId, catalogXmlId, measureCode, measureName are filled from the product card. The name passed in the request is not saved on creation. To give a catalog item a custom name, update it after creation via PATCH /v1/basket-items/:id.

Virtual item. When productId: 0, the item is not linked to a catalog. The fields name, price, productXmlId, catalogXmlId are set manually in the request and saved as passed.

A manual price enables customPrice. If you pass price, customPrice becomes true in the response — the item price is not recalculated when the catalog product price changes. Without price, it stays false.

Several items for one product. You can add the same productId to an order as several items — Bitrix24 does not merge them. To increase the quantity of an existing item, use PATCH /v1/basket-items/:id with quantity.

See also