How to Add a Line Item to an Order with an Arbitrary Price

<?php
// composer require bitrix24/b24phpsdk:"^3.0"
require_once 'vendor/autoload.php';

use Bitrix24\SDK\Services\ServiceBuilderFactory;
use Symfony\Component\EventDispatcher\EventDispatcher;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$log = new Logger('b24');
$log->pushHandler(new StreamHandler('php://stdout'));

$sb = (new ServiceBuilderFactory(new EventDispatcher(), $log))
    ->initFromWebhook('https://your-domain.bitrix24.com/rest/USER_ID/TOKEN/');

$result = $sb->getSaleScope()->basketItem()->add([
    'orderId' => 891,
    'productId' => 7075,
    'quantity' => 4,
    'currency' => 'EUR',
    'customPrice' => 'Y', // we set the price ourselves, the catalog price is not applied
    'basePrice' => 1030, // product price in the catalog
    'price' => 1100, // selling price
    'discountPrice' => -70, // markup, therefore the value is negative
]);

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

from b24pysdk import BitrixWebhook, Client
from b24pysdk.errors import BitrixAPIError

client = Client(
    BitrixWebhook(
        domain="your-domain.bitrix24.com",
        webhook_token="user_id/webhook_key",
    )
)

try:
    result = client.sale.basketitem.add(
        fields={
            "orderId": 891,
            "productId": 7075,
            "quantity": 4,
            "currency": "EUR",
            "customPrice": "Y",  # we set the price ourselves, the catalog price is not applied
            "basePrice": 1030,  # product price in the catalog
            "price": 1100,  # selling price
            "discountPrice": -70,  # markup, therefore the value is negative
        },
    ).response.result
    print(result)
except BitrixAPIError as error:
    print(error)

// Setup in an empty folder — go get will not work without go mod init:
//
//	go mod init example && go get github.com/bitrix24/b24gosdk
//
// Run:
//
//	export B24_WEBHOOK_URL='https://your-domain.bitrix24.com/rest/USER_ID/TOKEN/' && go run .
//
// The example is self-contained: it creates a product with a price and an order,
// adds a line item with a manual price, prints it, and cleans up after itself.
// It runs on any Bitrix24, nothing needs to be edited.
package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"log"
	"os"

	b24 "github.com/bitrix24/b24gosdk"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	core := b24.NewClient(os.Getenv("B24_WEBHOOK_URL")).Core()

	// --- setup: a product with a price and an empty order

	iblockID, err := firstCatalog(ctx, core)
	if err != nil {
		return err
	}
	productID, err := addProduct(ctx, core, iblockID, "Sample line item (b24gosdk)")
	if err != nil {
		return err
	}
	defer del(ctx, core, "catalog.product.delete", productID)

	if err := addPrice(ctx, core, productID, 1030); err != nil {
		return err
	}
	orderID, err := addOrder(ctx, core)
	if err != nil {
		return err
	}
	defer del(ctx, core, "sale.order.delete", orderID)

	// --- the scenario of this step itself

	// The price is set manually, therefore customPrice = "Y". The markup is expressed
	// by a NEGATIVE discountPrice: the base price is 1030, we sell for 1100.
	res, err := core.Call(ctx, "sale.basketitem.add", b24.Params{
		"fields": b24.Params{
			"orderId":       orderID,
			"productId":     productID,
			"quantity":      4,
			"currency":      "EUR",
			"customPrice":   "Y",
			"basePrice":     1030,
			"price":         1100,
			"discountPrice": -70,
		},
	})
	if err != nil {
		// The error code is compared with errors.Is rather than as a string: a typo in
		// a literal would compile and silently take another branch.
		if errors.Is(err, b24.ErrAccessDenied) {
			return fmt.Errorf("the webhook lacks the sale permission: %w", err)
		}
		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 in the response: %s", res.Result)
	}
	var item struct {
		ID        b24.ID  `json:"id"`
		Quantity  float64 `json:"quantity"`
		Price     float64 `json:"price"`
		BasePrice float64 `json:"basePrice"`
	}
	if err := json.Unmarshal(raw, &item); err != nil {
		return fmt.Errorf("parsing the line item: %w", err)
	}

	fmt.Printf("line item %d: %.0f x %.2f at the base price %.2f\n",
		item.ID, item.Quantity, item.Price, item.BasePrice)
	return nil
}

// --- helpers: preparing the data and cleaning up

func firstCatalog(ctx context.Context, core *b24.Core) (b24.ID, error) {
	res, err := core.Call(ctx, "catalog.catalog.list", b24.Params{
		"filter": b24.Params{"iblockTypeId": "CRM_PRODUCT_CATALOG"},
	}, b24.WithIdempotent())
	if err != nil {
		return 0, fmt.Errorf("catalog.catalog.list: %w", err)
	}
	var out struct {
		Catalogs []struct {
			IblockID b24.ID `json:"iblockId"`
		} `json:"catalogs"`
	}
	if err := json.Unmarshal(res.Result, &out); err != nil {
		return 0, err
	}
	if len(out.Catalogs) == 0 {
		return 0, fmt.Errorf("there is no commercial catalog in Bitrix24")
	}
	return out.Catalogs[0].IblockID, nil
}

func addProduct(ctx context.Context, core *b24.Core, iblockID b24.ID, name string) (b24.ID, error) {
	res, err := core.Call(ctx, "catalog.product.add", b24.Params{
		"fields": b24.Params{"iblockId": iblockID, "name": name, "active": "Y"},
	})
	if err != nil {
		return 0, fmt.Errorf("catalog.product.add: %w", err)
	}
	// add responds with the element key, while get responds with the product key for the same object.
	raw, ok := b24.Unwrap(res.Result, "element", "id")
	if !ok {
		return 0, fmt.Errorf("no element.id in %s", res.Result)
	}
	var id b24.ID
	return id, json.Unmarshal(raw, &id)
}

func addPrice(ctx context.Context, core *b24.Core, productID b24.ID, price float64) error {
	res, err := core.Call(ctx, "catalog.priceType.list", nil, b24.WithIdempotent())
	if err != nil {
		return fmt.Errorf("catalog.priceType.list: %w", err)
	}
	var types struct {
		PriceTypes []struct {
			ID b24.ID `json:"id"`
		} `json:"priceTypes"`
	}
	if err := json.Unmarshal(res.Result, &types); err != nil {
		return err
	}
	if len(types.PriceTypes) == 0 {
		return fmt.Errorf("there are no price types in Bitrix24")
	}
	_, err = core.Call(ctx, "catalog.price.add", b24.Params{
		"fields": b24.Params{
			"productId": productID, "catalogGroupId": types.PriceTypes[0].ID,
			"price": price, "currency": "EUR",
		},
	})
	return err
}

func addOrder(ctx context.Context, core *b24.Core) (b24.ID, error) {
	res, err := core.Call(ctx, "sale.persontype.list", nil, b24.WithIdempotent())
	if err != nil {
		return 0, fmt.Errorf("sale.persontype.list: %w", err)
	}
	var types struct {
		PersonTypes []struct {
			ID b24.ID `json:"id"`
		} `json:"personTypes"`
	}
	if err := json.Unmarshal(res.Result, &types); err != nil {
		return 0, err
	}
	if len(types.PersonTypes) == 0 {
		return 0, fmt.Errorf("there are no payer types in Bitrix24")
	}

	res, err = core.Call(ctx, "sale.order.add", b24.Params{
		"fields": b24.Params{
			"lid": "s1", "personTypeId": types.PersonTypes[0].ID, "currency": "EUR",
		},
	})
	if err != nil {
		return 0, fmt.Errorf("sale.order.add: %w", err)
	}
	raw, ok := b24.Unwrap(res.Result, "order", "id")
	if !ok {
		return 0, fmt.Errorf("no order.id in %s", res.Result)
	}
	var id b24.ID
	return id, json.Unmarshal(raw, &id)
}

// del removes what was created. A cleanup error is printed but not returned: it must
// not mask the real error of the scenario.
func del(ctx context.Context, core *b24.Core, method string, id b24.ID) {
	if _, err := core.Call(ctx, method, b24.Params{"id": id}); err != nil {
		fmt.Fprintf(os.Stderr, "%s(%d): %v\n", method, id, err)
	}
}

<?php
// composer require bitrix24/b24phpsdk:"^3.0"
require_once 'vendor/autoload.php';

use Bitrix24\SDK\Services\ServiceBuilderFactory;
use Symfony\Component\EventDispatcher\EventDispatcher;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$log = new Logger('b24');
$log->pushHandler(new StreamHandler('php://stdout'));

$sb = (new ServiceBuilderFactory(new EventDispatcher(), $log))
    ->initFromWebhook('https://your-domain.bitrix24.com/rest/USER_ID/TOKEN/');

$result = $sb->getSaleScope()->basketItem()->add([
    'orderId' => 891,
    'productId' => 0, // the line item is not in the catalog
    'name' => 'Equipment setup',
    'quantity' => 2,
    'currency' => 'EUR',
    'customPrice' => 'Y',
    'basePrice' => 1000, // price without a discount
    'price' => 900, // selling price
    'discountPrice' => 100, // discount, therefore the value is positive
    'canBuy' => 'Y',
    'weight' => 40,
    'measureCode' => '796',
    'measureName' => 'pcs',
    'sort' => 400,
    'xmlId' => 'service-setup-1',
    'dimensions' => 'a:3:{s:5:"WIDTH";i:244;s:6:"HEIGHT";i:100;s:6:"LENGTH";i:31;}', // serialized array
    'vatRate' => 0.1, // rate of 10 %
    'vatIncluded' => 'Y',
    'productXmlId' => 'service-setup',
]);

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

from b24pysdk import BitrixWebhook, Client
from b24pysdk.errors import BitrixAPIError

client = Client(
    BitrixWebhook(
        domain="your-domain.bitrix24.com",
        webhook_token="user_id/webhook_key",
    )
)

try:
    result = client.sale.basketitem.add(
        fields={
            "orderId": 891,
            "productId": 0,  # the line item is not in the catalog
            "name": "Equipment setup",
            "quantity": 2,
            "currency": "EUR",
            "customPrice": "Y",
            "basePrice": 1000,  # price without a discount
            "price": 900,  # selling price
            "discountPrice": 100,  # discount, therefore the value is positive
            "canBuy": "Y",
            "weight": 40,
            "measureCode": "796",
            "measureName": "pcs",
            "sort": 400,
            "xmlId": "service-setup-1",
            "dimensions": 'a:3:{s:5:"WIDTH";i:244;s:6:"HEIGHT";i:100;s:6:"LENGTH";i:31;}',  # serialized array
            "vatRate": 0.1,  # rate of 10 %
            "vatIncluded": "Y",
            "productXmlId": "service-setup",
        },
    ).response.result
    print(result)
except BitrixAPIError as error:
    print(error)

$result = $sb->getSaleScope()->basketItem()->list(
    ['id', 'productId', 'name', 'quantity', 'basePrice', 'price', 'discountPrice', 'customPrice'],
    ['=orderId' => 891]
);

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

try:
    result = client.sale.basketitem.list(
        select=["id", "productId", "name", "quantity", "basePrice", "price", "discountPrice", "customPrice"],
        filter={"=orderId": 891},
    ).response.result
    print(result)
except BitrixAPIError as error:
    print(error)