For AI agents: markdown of this page — /docs-content-en/entities/basket-items/create.md documentation index — /llms.txt

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 Req. Description
orderId number yes Order identifier. Source: GET /v1/orders
productId number yes Catalog product identifier. Source: GET /v1/catalog-products. The value 0 creates a virtual item with no catalog link
currency string yes Item currency. List: GET /v1/currencies
quantity number yes Quantity
name string no Item name. When productId > 0, it is substituted from the product card — the passed value is not saved on creation. When productId: 0, it is saved as passed
price number no Price per unit. For a virtual item, set manually. Passing price enables customPrice
basePrice number no Base price before discount. Defaults to price
discountPrice number no Discount amount per unit. Defaults to 0
customPrice boolean no Protects the price from auto-recalculation when the product changes in the catalog. When price is passed, it is set to true. Defaults to false
vatRate number no VAT rate as a fraction of one. 0.20 = 20%, 0.10 = 10%, 0 — no VAT
vatIncluded boolean no Whether VAT is included in the price. Defaults to true
weight number no Unit weight in grams
measureCode number no Measurement unit code. 796 — pcs, 163 — g, 006 — m
productXmlId string no External product identifier. For a virtual item, set manually
catalogXmlId string no External catalog identifier. For a virtual item, set manually
xmlId string no External item identifier

Examples

The examples below create a virtual item with productId: 0 — for it, 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 app

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 app

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

Returns the full object of the created item.

Field Type Description
id number Identifier of the created item
name string Name. For a catalog product — from the product card, for a virtual item — as passed
price number Price per unit
customPrice boolean true if the price is set manually via price
productXmlId string | null External product identifier. null for a virtual item with no passed value
catalogXmlId string | null External catalog identifier. null for a virtual item with no passed value
dateInsert datetime Creation date

Full field set — 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
422 BITRIX_ERROR Required fields not passed — the message contains their list
422 BITRIX_ERROR Non-existent orderId or productId — the item is not saved
403 SCOPE_DENIED The API key lacks the sale scope
401 TOKEN_MISSING The 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