Add Item (Position) to the Cart of an Existing Order sale.basketitem.add

{% note tip "" %}

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

{% endnote %}

Scope: sale

Who can execute the method: administrator

The method sale.basketitem.add adds an item to the cart of an existing order.

Method Parameters

{% include Note on required parameters %}

#| || Name type | Description || || fields* object | Field values for creating an item (position) in the cart of the order || |#

Parameter fields

{% include Note on required parameters %}

Field values marked with ** will be taken from the product data on the site if a valid product identifier is passed in the productid field. If the product does not exist on the site, the field must be filled in manually. {.b24-info}

#| || Name type | Description || || orderId* sale_order.id | Order identifier || || sort integer | Position in the list of order items || || productid* catalog_product.id | Product/variation identifier.

For products that are not on the site/account, it may be zero || || price double | Price including markups and discounts (see the customPrice field below).

The field will be filled automatically if customPrice !== ‘Y’ || || basePrice double | Original price excluding markups and discounts (see the customPrice field below).

The field will be filled automatically if customPrice !== ‘Y’ || || discountPrice double | Amount of the final discount or markup (see the customPrice field below).

The field will be filled automatically if customPrice !== ‘Y’ || || currency* crm_currency.CURRENCY | Currency of the price. Must match the currency of the order || || customPrice string | Is the price specified manually. Possible values:

Y — yes
N — no

If Y is specified, catalog data will be ignored. The parameters price, basePrice, and discountPrice must be explicitly set so that the condition basePrice = price + discountPrice is met || || quantity* double | Quantity of the product || || xmlId string | External code of the cart item || || name*,** string | Product name || || weight** integer | Weight of the product || || dimensions** string | Dimensions of the product (serialized array) || || measureCode** catalog_measure.code | Unit code of the product || || measureName** catalog_measure.symbol | Name of the unit of measure || || canBuy** string | Availability flag of the product. Possible values:

Y — yes
N — no || || vatRate** double | Tax rate as a fraction of one: 0.1 means 10 %. To specify the rate "No VAT", an empty string must be passed || || vatIncluded** string | Flag indicating whether VAT or tax is included in the product price. Possible values:
Y — yes
N — no || || catalogXmlId** string | External code of the product catalog || || productXmlId** string | External code of the product || |#

Code Examples

{% include Note on examples %}

{% list tabs %}

cURL (Webhook)

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"fields":{"orderId":5147,"quantity":2,"productId":6544,"currency":"USD"}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/sale.basketitem.add

cURL (OAuth)

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"fields":{"orderId":5147,"quantity":2,"productId":6544,"currency":"USD"},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/sale.basketitem.add

JS (TS)

// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame, ISODate } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

// Shape of the payload returned in result (match the "response handling" section of the page)
type BasketItemAddResult = {
  basketItem: {
    id: number
    orderId: number
    productId: number
    name: string
    sort: number
    quantity: number
    price: number
    basePrice: number
    discountPrice: number
    currency: string
    customPrice: string
    vatRate: number | null
    vatIncluded: string
    weight: number
    dimensions: string
    measureCode: string
    measureName: string
    canBuy: string
    xmlId: string
    catalogXmlId: string
    productXmlId: string
    dateInsert: ISODate | null
    dateUpdate: ISODate | null
    properties: unknown[]
    reservations: unknown[]
  }
}

try {
  const response = await $b24.actions.v2.call.make<BasketItemAddResult>({
    method: 'sale.basketitem.add',
    params: {
      fields: {
        orderId: 5147,
        quantity: 2,
        productId: 6544,
        currency: 'USD',
      },
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info(result.basketItem.id, result.basketItem.name, result.basketItem.price)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}

JS (UMD)

<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function addBasketItem() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'sale.basketitem.add',
        params: {
          fields: {
            orderId: 5147,
            quantity: 2,
            productId: 6544,
            currency: 'USD',
          },
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info(result.basketItem.id, result.basketItem.name, result.basketItem.price)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', addBasketItem)
</script>

Python

from b24pysdk.errors import BitrixAPIError, BitrixSDKException

fields = {
    "orderId": 5147,
    "quantity": 2,
    "productId": 6544,
    "currency": "USD",
}

try:
    bitrix_response = client.sale.basketitem.add(
        fields=fields,
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Bitrix API error",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Bitrix SDK error: {error.message}")
except Exception as error:
    print(f"Unexpected error: {error}")

PHP

try {
    $response = $b24Service
        ->core
        ->call(
            'sale.basketitem.add',
            [
                'fields' => [
                    'orderId'   => 5147,
                    'quantity'  => 2,
                    'productId' => 6544,
                    'currency'  => 'USD',
                ],
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'Success: ' . print_r($result, true);

} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error adding basket item: ' . $e->getMessage();
}

BX24.js

BX24.callMethod(
    "sale.basketitem.add",
    {
        fields: { // minimum set of required fields
            orderId: 5147,
            quantity: 2,
            productId: 6544,
            currency: 'USD',
        }
    },
)
    .then(
        function(result)
        {
            if (result.error())
            {
                console.error(result.error());
            }
            else
            {
                console.log(result.data());
            }
        },
        function(error)
        {
            console.info(error);
        }
    );

PHP CRest

require_once('crest.php');

$result = CRest::call(
    'sale.basketitem.add',
    [
        'fields' =>
        [
            'orderId' => 5147,
            'quantity' => 2,
            'productId' => 6544,
            'currency' => 'USD',
        ]
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';

// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "sale.basketitem.add", b24.Params{
	"fields": b24.Params{
		"orderId":   5147,
		"quantity":  2,
		"productId": 6544,
		"currency":  "EUR",
	},
})
if err != nil {
	return fmt.Errorf("sale.basketitem.add: %w", err)
}

// The method wraps the response in an object with the "basketItem" key.
raw, ok := b24.Unwrap(res.Result, "basketItem")
if !ok {
	return fmt.Errorf("no basketItem key in the response")
}

var item struct {
	BasePrice    int    `json:"basePrice"`
	CanBuy       string `json:"canBuy"`
	CatalogXmlID string `json:"catalogXmlId"`
	Currency     string `json:"currency"`
	CustomPrice  string `json:"customPrice"`
	DateInsert   string `json:"dateInsert"`
}
if err := json.Unmarshal(raw, &item); err != nil {
	return fmt.Errorf("parse response: %w", err)
}
fmt.Println(item.BasePrice, item.CanBuy)

{% endlist %}

{% note tip "Typical use-cases and scenarios" %}

{#T}

{% endnote %}

Response Handling

HTTP status: 200

{
    "result": {
        "basketItem": {
            "basePrice": 1000,
            "canBuy": "Y",
            "catalogXmlId": "FUTURE-QUICKBOOKS-CATALOG",
            "currency": "USD",
            "customPrice": "N",
            "dateInsert": "2024-04-23T15:59:37+02:00",
            "dateUpdate": "2024-04-23T15:59:37+02:00",
            "dimensions": "a:3:{s:5:\"WIDTH\";N;s:6:\"HEIGHT\";N;s:6:\"LENGTH\";N;}",
            "discountPrice": 100,
            "id": 6790,
            "measureCode": "163",
            "measureName": "g",
            "name": "Product",
            "orderId": 5147,
            "price": 900,
            "productId": 1245,
            "productXmlId": "1245",
            "properties": [],
            "quantity": 1,
            "reservations": [],
            "sort": 100,
            "vatIncluded": "N",
            "vatRate": null,
            "weight": 0,
            "xmlId": "bx_6627bec8c4fdc"
        }
    },
    "total": 1,
    "time": {
        "start": 1713880776.108755,
        "finish": 1713880777.704221,
        "duration": 1.595465898513794,
        "processing": 0.973701000213623,
        "date_start": "2024-04-23T15:59:36+02:00",
        "date_finish": "2024-04-23T15:59:37+02:00",
        "operating": 0
    }
}

Returned Data

#| || Name type | Description || || result object | Root element of the response || || basketItem sale_basket_item | Object with data of the created item (position) in the cart || || total integer | Number of processed records || || time time | Information about the execution time of the request || |#

Error Handling

HTTP status: 400

{
    "error":0,
    "error_description":"error"
}

{% include notitle error handling %}

Possible Error Codes

#| || Code | Description || || 200140400007 | basket item is not saved - bad data

The item was not created. The error occurs if an invalid product identifier is passed or if the product is inactive || || 200140400008 | Required fields: fields[ORDER_ID]

Order identifier is not specified || || 200140400009 | Order not found

Order not found || || 200140400011 | Currency must be the currency of the order

The currency of the item does not match the currency of the order || || 200040300010 | Insufficient permissions to add || || 100 | Required parameters are not specified || || 0 | Other errors (e.g., fatal errors) || |#

{% include system errors %}

Navigation Menu

Uh oh!

Add Item (Position) to the Cart of an Existing Order sale.basketitem.add

Method Parameters

Parameter fields

Code Examples

Response Handling

Returned Data

Error Handling

Possible Error Codes

Continue Learning

Uh oh!

FilesExpand file tree

sale-basket-item-add.md

Latest commit

History

sale-basket-item-add.md

File metadata and controls

Add Item (Position) to the Cart of an Existing Order sale.basketitem.add

Method Parameters

Parameter fields

Code Examples

Response Handling

Returned Data

Error Handling

Possible Error Codes

Continue Learning