sale)sale owns cart (basket), orders, payments, shipments, discounts, statuses, and history. Product master data, prices, stock live in catalog + iblock. Baseline: main 23.0+.
\\Bitrix\\Main\\Loader::includeModule('sale');\n\\Bitrix\\Main\\Loader::includeModule('catalog'); // products, prices, stock, reservation\n| Task | \nAPI | \n
|---|---|
| Create/change basket, order, payment, shipment | \nObject model Bitrix\\Sale\\* (validates, saves collections, fires events, writes history) | \n
| Lists, reports, aggregates | \nORM Bitrix\\Sale\\Internals\\*Table (OrderTable, BasketTable, PaymentTable, ShipmentTable) — read-only for order data | \n
| Settings/dictionaries via code | \nProfile ORM: PersonTypeTable, OrderPropsTable, StatusTable (+StatusLangTable), OrderPropsGroupTable — writes allowed | \n
| Pick a configured service | \nManagers: PaySystem\\Manager, Delivery\\Services\\Manager, Cashbox\\Manager/CheckManager, Services\\Company\\Manager, DiscountCouponsManager | \n
| Operations with no full D7 replacement | \nLegacy CSale*: CSaleOrder::CanUser*() (rights), CSaleOrderChange (history read), CSaleDiscount::Add/Update (cart rules), CSaleOrderUserProps (buyer profiles), CSaleUserAccount (account balance), CSaleOrderTax (tax rows) | \n
Never change an order via OrderTable::update() or create payments/shipments as raw ORM rows — collections, recalcs, events, and history desync. Never Order::load() in a loop for a list — use OrderTable::getList() / Order::getList(). Don't mix legacy CSale* writes with a loaded Order object in memory.
Anonymous and authorized carts are keyed by FUSER (Bitrix\\Sale\\Fuser), not USER_ID.
$fuserId = Fuser::getId(); // creates if missing\n$fuserId = Fuser::getId(true); // skip create → null if none\n$fuserId = Fuser::getIdByUserId($userId); // false if cannot resolve/create\nUSER_ID (site account, required on saved order) and FUSER_ID (basket owner) are different — don't substitute one for the other.
<?php declare(strict_types=1);\n\nuse Bitrix\\Catalog\\Product\\Basket as CatalogBasket;\nuse Bitrix\\Sale\\Basket;\nuse Bitrix\\Sale\\Basket\\RefreshFactory;\nuse Bitrix\\Sale\\Fuser;\n\n$basket = Basket::loadItemsForFUser(Fuser::getId(), $siteId); // only rows with ORDER_ID = null\n\n// Preferred for catalog products: sets module, provider, and product data itself\n$r = CatalogBasket::addProductToBasket($basket, ['PRODUCT_ID' => $productId, 'QUANTITY' => 1], ['SITE_ID' => $siteId]);\n// merges into an existing row by default; pass ['USE_MERGE' => 'N'] as 4th arg for a separate row\n\n// Manual alternative:\n$item = $basket->createItem('catalog', $productId);\n$item->setFields(['QUANTITY' => 1, 'PRODUCT_PROVIDER_CLASS' => CatalogBasket::getDefaultProviderName()]);\n$basket->refresh(RefreshFactory::createSingle($item->getBasketCode())); // provider fills PRICE/CURRENCY/NAME/VAT/weight\n\n$result = $basket->save(); // only for a basket NOT bound to an order\nPRICE/CURRENCY for catalog products — the provider does. Own pricing: CUSTOM_PRICE => 'Y' + PRICE + CURRENCY.PRODUCT_ID, never the parent. Verify the element is a product (Bitrix\\Catalog\\ProductTable) before adding.$order->getBasket(), save via Order::save() — never loadItemsForFUser() / $basket->save() for it.$basket->refresh() (refreshData() is deprecated), then $basket->getOrderableItems() — separate basket with only purchasable, non-delayed items.$item->getPropertyCollection()->createItem() / redefine(). Prices: getPrice(), getBasePrice(), getPriceWithVat(), getDiscountPrice().Discount::buildFromBasket($basket, new Discount\\Context\\Fuser($basket->getFUserId())) → calculate() → $basket->applyDiscount($data['BASKET_ITEMS']). Never for an order-bound basket.Order of operations matters: basket → order → person type → basket in → properties → shipment → delivery calc → payment → doFinalAction(true) → sync payment SUM → re-check restrictions → save().
<?php declare(strict_types=1);\n\nuse Bitrix\\Sale\\Delivery\\Services\\Manager as DeliveryManager;\nuse Bitrix\\Sale\\Order;\nuse Bitrix\\Sale\\PaySystem\\Manager as PaySystemManager;\nuse Bitrix\\Sale\\Services\\Base\\RestrictionManager;\n\n$order = Order::create($siteId, $userId); // currency: site's, else base\n$order->setPersonTypeId($personTypeId); // BEFORE getPropertyCollection(); not validated vs site\n$order->setBasket($orderableBasket); // new (unsaved) order only\n\n// Properties (set depends on person type)\n$prop = $order->getPropertyCollection()->getItemByOrderPropertyCode('PHONE');\n$prop?->setValue($phone); // each setValue returns Result\n\n// Shipment: create user shipment, bind basket items, pick allowed delivery\n$shipment = $order->getShipmentCollection()->createItem(); // system shipment exists already — never assign it a service\nforeach ($order->getBasket() as $basketItem) {\n $shipmentItem = $shipment->getShipmentItemCollection()->createItem($basketItem);\n $shipmentItem->setQuantity($basketItem->getQuantity());\n}\n$deliveries = DeliveryManager::getRestrictedObjectsList($shipment);\n$shipment->setDeliveryService($deliveries[$deliveryId] ?? throw new \\RuntimeException('delivery unavailable'));\n$order->getShipmentCollection()->calculateDelivery();\n\n// Payment: create, preliminary SUM, pick allowed pay system\n$payment = $order->getPaymentCollection()->createItem();\n$payment->setField('SUM', $order->getPrice());\n$allowed = PaySystemManager::getListWithRestrictions($payment, RestrictionManager::MODE_CLIENT);\nisset($allowed[$paySystemId]) or throw new \\RuntimeException('pay system unavailable');\n$payment->setPaySystemService(PaySystemManager::getObjectById($paySystemId));\n\n$order->doFinalAction(true); // discounts, taxes, totals — check Result\n$payment->setField('SUM', $order->getPrice()); // sync after final calc\n// re-check getRestrictedObjectsList / getListWithRestrictions here — totals may change availability\n\n$saveResult = $order->save(); // check isSuccess() AND getWarningMessages()\n$orderId = $saveResult->getId();\nPayment and user shipment are optional at first save (digital goods, deferred flows) — skip those blocks; add later on the loaded order. Idempotency for integrations: store operation key yourself (XML_ID is not unique-constrained). Load later: Order::load($id), Order::loadByAccountNumber($number), Order::loadByFilter([...]); lock while editing with Order::lock()/isLocked()/unlock().
Work on one loaded object, save once. After a change decide what to rerun:
\n| Change | \ncalculateDelivery | \ndoFinalAction(true) | \nsync unpaid payments SUM | \n
|---|---|---|---|
| Status, cancel, mark, comment, tracking, allow-delivery | \n– | \n– | \n– | \n
| Location/address in restrictions | \nyes | \nyes | \nif price changed | \n
| Basket items/quantity; delivery service/cost; shipment removal | \nyes | \nyes | \nif price changed | \n
| Coupon/discount/tax data | \nif delivery affected | \nyes | \nif price changed | \n
ShipmentItem::setQuantity() first, then BasketItem::setField('QUANTITY'); up: basket first, then shipment. Then refresh the item, recalc, save.setField('CANCELED', 'Y') (+ REASON_CANCELED); blocked while a paid payment or shipped shipment exists. Order::delete() is a service-only hard delete — never use for customer refusal.PERSON_TYPE_ID change is a migration (property values are not remapped). CURRENCY/USER_ID are not changeable via setField(). Don't write SUM_PAID/PAYED directly.Setting (OrderPropsTable, bound to a person type; ENTITY_TYPE ORDER/SHIPMENT) vs value in an order (PropertyValueCollection). Create settings via OrderPropsGroupTable::add() + OrderPropsTable::add() in migrations, never during checkout.
getItemByOrderPropertyCode() (first match), getItemByOrderPropertyId(), by role: getDeliveryLocation(), groups via getGroups().LOCATION takes the internal location code, not a name. ENUM takes variant VALUE (options via $propertyValue->getPropertyObject()->getOptions()); MULTIPLE=Y takes an array. Files/forms: PropertyValueCollection::setValuesFromPost($_POST, $_FILES) + verify().isRequired() + checkRequiredValue().Order::save() only; never write OrderPropsValueTable directly.STATUS_ID, initial N, final F, class Bitrix\\Sale\\OrderStatus. Shipment: own STATUS_ID, DN→DF, class DeliveryStatus. Dictionary StatusTable (TYPE_ORDER/TYPE_SHIPMENT) + StatusLangTable names.OrderStatus::getAllowedUserStatuses($userId, $currentStatusId); operations per status: getStatusesUserCanDoOperations(), canGroupDoOperations() (operations: view, update, delete, cancel, mark, payment, delivery, deduction, from, to).CSaleOrder: CanUserViewOrder(), CanUserUpdateOrder() (pass 0, $groups, $siteId for create), CanUserCancelOrder(), CanUserChangeOrderStatus(), CanUserChangeOrderFlag($id, 'PERM_PAYMENT'|'PERM_DELIVERY'|'PERM_DEDUCTION', $groups), CanUserDeleteOrder(). Check view rights before Order::load().D denied, P company binding, U order processing (still needs site + status-task grants), W full.OrderHistory on save; read via legacy CSaleOrderChange::GetList() (@TYPE => ['ORDER_STATUS_CHANGED', ...]).Register via EventManager in init.php. Key ones: OnSaleOrderBeforeSaved (may modify/deny), OnSaleOrderSaved (IS_NEW, IS_CHANGED; result ignored), deferred after save: OnSaleStatusOrderChange (VALUE/OLD_VALUE), OnSaleOrderPaid, OnSaleOrderCanceled, OnSaleStatusShipmentChange, OnShipmentDeducted, OnShipmentAllowDelivery, OnShipmentTrackingNumberChange; per-entity On[Before]Sale{BasketItem,Payment,Shipment,ShipmentItem,PropertyValue}SetField and OnSale*EntitySaved; basket: OnSaleBasketItemBeforeSaved/Saved, OnSaleBasketItemRefreshData; final calc: On{Before,After}SaleOrderFinalAction.
Never call $order->save() from OnSaleOrderSaved — recursion. Mutate in OnSaleOrderBeforeSaved instead, or queue a job that reloads the order. OnBefore* handlers returning EventResult::ERROR surface as setField()/save() errors.
getPaymentCollection()->createItem($service); several payments per order = split/partial pay. Available: PaySystem\\Manager::getListWithRestrictions($payment, MODE_CLIENT|MODE_MANAGER) (or getListWithRestrictionsByOrder() pre-payment).$payment->getPaySystem()->initiatePay($payment, $request, BaseServiceHandler::STRING) → ServiceResult (getTemplate(), getPaymentUrl(), QR). Manual confirm: $payment->setPaid('Y'); refund: $payment->setReturn(Payment::RETURN_PS|RETURN_INNER|RETURN_NONE), partial via Service::refund($payment, $sum) (handler must implement IRefund). Recurring: IRecurring, isRecurring()/repeatRecurrent().PaySystem\\Manager::getInnerPaySystemId(), Payment::isInner(). Balance itself: legacy CSaleUserAccount::GetByUserID() / UpdateAccount($userId, $delta, ...) — pass the delta, not the new total; journal read via Internals\\UserTransactTable. Buyer aggregates: Bitrix\\Sale\\BuyerStatistic (per user+site+currency)./local/php_interface/include/sale_payment/<code>/ (handler.php extending PaySystem\\ServiceHandler, .description.php, template/). Legacy /bitrix/modules/sale/payment/ unsupported since sale 22.200.0. Callback entry: /bitrix/tools/sale_ps_result.php (verify signature/sum/currency; handle repeated notifications idempotently). Custom restrictions: extend Services\\Base\\Restriction, register on onSalePaySystemRestrictionsClassNamesBuildList.Delivery\\Services\\Manager::getRestrictedObjectsList($shipment) or getRestrictedList($shipment, Restrictions\\Manager::MODE_CLIENT). Single service object: getObjectById() — never trust a raw request ID without the restricted list.ShipmentCollection::calculateDelivery() (all non-system shipments; skips CUSTOM_PRICE_DELIVERY='Y') or Manager::calculateDeliveryPrice($shipment, $deliveryId, $extraServices) → CalculationResult (price, period).isSystem()) with undistributed quantity — never assign it a service or edit it. Partial/split shipments: distribute quantities; guard with getBasketItemDistributedQuantity().allowDelivery()/disallowDelivery(), deduct via setField('DEDUCTED', 'Y'), TRACKING_NUMBER, setStoreId() for pickup. Custom handler: extend Delivery\\Services\\Base (calculateConcrete(), getConfigStructure()), register on onSaleDeliveryHandlersClassNamesBuildList, add via Manager::add(); restrictions on onSaleDeliveryRestrictionsClassNamesBuildList; extra services in Delivery\\ExtraServices\\* + Shipment::setExtraServices().CSaleDiscount::Add()/Update() (CONDITIONS/ACTIONS trees, PRIORITY+SORT, LAST_DISCOUNT) — no full D7 replacement; delete via Internals\\DiscountTable::delete(). Never compute discounts by hand or write final prices.Discount::buildFromBasket() + calculate() + applyDiscount(); saved order → Order::doFinalAction(true) (never buildFromBasket() on an order basket).DiscountCouponsManager::init(MODE_CLIENT|MODE_MANAGER|MODE_ORDER [, userId/orderId]) → add($code). add() === true does not mean the discount applied — recalc, then get(true, ['COUPON' => $code], true, true) and check STATUS === STATUS_APPLYED. Coupon rows: Internals\\DiscountCouponTable (TYPE_ONE_ORDER, TYPE_MULTI_ORDER + MAX_USE).$order->getDiscount()->getApplyResult(); saved orders: OrderDiscount::loadResultFromDb($orderId), rows in Internals\\OrderRulesTable.Shipment::tryReserve() / tryUnreserve(); full-reserve check isReserved(). Per-item store rows: BasketItem::getReserveQuantityCollection() (create() → setStoreId() then setQuantity()). Always finish with Order::save() — never edit RESERVED* table fields.Shipment::setField('DEDUCTED', 'Y'); catalog provider updates stock (StoreProductTable.AMOUNT/QUANTITY_RESERVED) on save. Set the store first when inventory management is on.Sale\\Configuration::getProductReservationCondition() → ReserveCondition::ON_CREATE|ON_PAY|ON_FULL_PAY|ON_ALLOW_DELIVERY|ON_SHIP; TTL getProductReserveClearPeriod(); stale reserves cleaned by Helpers\\ReservedProductCleaner. Available qty: Reservation\\BasketReservationService::getAvailableCountForBasketItem()/ForOrder().select, batch related tables by ORDER_ID array (no N+1); order-level flags PAYED/DEDUCTED avoid loading collections. Mass updates: pick IDs in chunks, then load/change/save each order.Bitrix\\Sale\\Archive\\Manager::getList()/getById(); returnArchivedOrder() returns a read-only object (don't save it as active). Combine active + archive explicitly in reports.doFinalAction(true) and one save() per logical operation; check Result::isSuccess() and getWarningMessages() (warnings can hide sub-object failures — reload and verify critical state).sale enables controllers.restIntegration. Prefer thin Engine controllers + services reusing sale entities (bitrix-controllers); standard public checkout is bitrix:sale.order.ajax — customize business logic via the object model, not by patching component internals.
sale (+ catalog) included; API level chosen per task (object model / ORM read / manager / legacy).Fuser; catalog lines via addProductToBasket or provider class + refresh.doFinalAction(true) → SUM sync → restriction re-check → save().CSaleOrder::CanUser*, getAllowedUserStatuses) before user-driven load/changes.CANCELED='Y', not Order::delete(); no direct ORM writes to order tables.STATUS_APPLYED), not just add().Results checked incl. warnings; no save() from OnSaleOrderSaved.bitrix-catalog, bitrix-iblocks, bitrix-result-and-errors, bitrix-events, bitrix-controllers, bitrix-service-locator.