Attention! Shipments are always associated with orders. It's categorically prohibited to use the method \Bitrix\Sale\Shipment::save() for saving shipments. When updating a shipment changes, associated entities may be updated, which will not be saved. Saving action must be performed via the order method: \Bitrix\Sale\Order::save(). Additionally, calling \Bitrix\Sale\Shipment::save() will generate error E_WARNING.

One of this architecture specifics is the available hidden system shipment. This shipment contains products that were not distributed by other shipments.

When a product is added to shopping cart, it automatically is included into a system shipment. When we add a product to shipment, the following can occur inside the system:

  • either amount of products decreases,
  • or product will fully move from system shipment into a standard shipment.

In the first case, no actions be done with this shipment: it cannot be shipped, nor deleted. That's why, its better to exclude it when overviewing the shipments (see example Handling shipment collection without a system shipment or Receiving a specific shipment).

  • Receiving shipments:
  • Receiving a specific shipment
  • Adding shipment
  • Editing a shipment
  • Deleting a shipment
  • Getting delivery cost
  • Getting a shipment status
  • Managing delivery permission flag
  • Managing delivery status flag
  • Managing delivery cost
  • Getting amount of products distributed by shipments
  • Getting total deliveries cost in order:
  • Setting a pick-up location for shipment
  • Getting list of available delivery services with account of configured restrictions
  • Receiving shipments:

    • Handling shipment collection
      $collection = $order->getShipmentCollection();
      foreach ($collection as $shipment)
      	// ...
    • Handling shipment collection without a system shipment
      $collection = $order->getShipmentCollection()->getNotSystemItems();
      foreach ($collection as $shipment)
      	// ...
    • Handling an array

      In addition to objects, there is an option to directly query database via the method \Bitrix\Sale\ShipmentCollection::getList($parameters), or via \Bitrix\Sale\Shipment::getList($parameters). Both these methods work similarly.

      Method always returns object Bitrix\Main\DB\Result that can be used to get data using the method fetch().

      Parameter Description Available from version
      $parameters Array with structure fully matching ORM's getList.
      // getting list of shipments for order 1234
      $dbRes = \Bitrix\Sale\ShipmentCollection::getList([
      	'select' => ['*'],
      	'filter' => [
      		'=ORDER_ID' => 1234, 
      while ($item = $dbRes->fetch())

    Getting a specific shipment

    $collection = $order->getShipmentCollection();
    • by ID
      $shipment = $collection->getItemById($id);
    • by internal index
      $shipment = $collection->getItemByIndex($index);
    • by code
      $shipment = $collection->getItemByShipmentCode($code);

    Adding a shipment

    • Variant 1:
       * $collection - object class \Bitrix\Sale\ShipmentCollection
      $shipment = $collection->createItem();
      $shipment->setField('DELIVERY_ID', 10);
       * method \Bitrix\Sale\ShipmentCollection::createItem receives one optional parameter: $delivery - delivery service object
      $service = \Bitrix\Sale\Delivery\Services\Manager::getObjectById(10);
      $shipment = $collection->createItem($service);
    • Variant 2:
       * payment system object can be passed to \Bitrix\Sale\Shipment::create as well
      $service = \Bitrix\Sale\Delivery\Services\Manager::getObjectById(10);
      $shipment = \Bitrix\Sale\Shipment::create($collection, $service);

    Editing a shipment

    Possible variants:

    • $r = $payment->setField($fieldName, $value);
    • $r = $payment->setFields([
      	$fieldName1 => $value1,
      	$fieldName2 => $value2,

    In both cases, method results is class object \Bitrix\Sale\Result.

    List of fields available for editing:

    "STATUS_ID", // shipment status
    "BASE_PRICE_DELIVERY", // delivery base cost
    "ALLOW_DELIVERY", // delivery approved flag: Y/N
    "DATE_ALLOW_DELIVERY", // delivery approved date 
    "EMP_ALLOW_DELIVERY_ID", // user ID who allowed delivery
    "DEDUCTED",  // shipped flag: Y/N
    "DATE_DEDUCTED", // shipped date
    "EMP_DEDUCTED_ID", // user ID, who shipped the delivery
    "REASON_UNDO_DEDUCTED", // reason for cancelled shipment
    "DELIVERY_ID", //  delivery service ID
    "DELIVERY_DOC_NUM", // number of shipment document
    "DELIVERY_DOC_DATE", // shipment document date
    "TRACKING_NUMBER", // track number
    "XML_ID", //XML_ID
    "PARAMS", // 
    "DELIVERY_NAME", // delivery service name
    "COMPANY_ID", // company ID, performing shipments
    'MARKED', // marked shipment
    'REASON_MARKED', // reason for marking
    'DATE_MARKED', // marking date
    'EMP_MARKED_ID', // who marked the shipment
    "CANCELED", // cancelled shipment
    'RESPONSIBLE_ID', // user ID, who is responsible for shipment
    'EMP_RESPONSIBLE_ID', // user ID, who assigned a responsible party
    'DATE_RESPONSIBLE_ID', // date assigned responsible
    "COMMENTS", // comment
    "CURRENCY", // currency
    "CUSTOM_PRICE_DELIVERY", // Flag for manually set price
    'UPDATED_1C', // attribute for updated price via 1С accounting system
    'ID_1C', // ID in 1С accounting system
    'VERSION_1C', // shipment document version in 1С accounting system
    'EXTERNAL_PAYMENT', // flag Y/N: external shipment
    "TRACKING_STATUS", // tracking status
    "TRACKING_LAST_CHECK", // date of recent shipment status check
    "TRACKING_DESCRIPTION", // shipment status description
    'ACCOUNT_NUMBER', // shipment number
    'DISCOUNT_PRICE' // shipment's discount/extra charge total amount

    Deleting a shipment

    Returns object type \Bitrix\Sale\Result.

    $r = $shipment->delete();
    if ($result->isSuccess())

    Getting delivery cost

    $price = $shipment->getPrice();

    Getting shipment status

    $statusId = $shipment->getField('STATUS_ID');

    Managing allowed delivery flag

    • Delivery is allowed
      $r = $shipment->allowDelivery();
      if (!$r->isSuccess())
    • Delivery is denied
      $r = $shipment->disallowDelivery();
      if (!$r->isSuccess())

    Managing shipped delivery flag

    • Delivery shipped
      $r = $shipment->setField('DEDUCTED', 'Y');
      if (!$r->isSuccess())
    • Delivery not shipped
      $r = $shipment->setField('DEDUCTED', 'N');
      if (!$r->isSuccess())

    Updating delivery cost

    $price = 123;

    Method also can receive a second passed parameter: custom price. When Yes, passes true. Default value is false.

    $shipment->setBasePriceDelivery($price, true);

    Getting amount of products distributed by shipments

    $shipmentCollection = $order->getShipmentCollection();
    $quantity = $collection->getBasketItemDistributedQuantity();

    Getting total deliveries cost in order:

    • without discounts/extra charges
      $shipmentCollection = $order->getShipmentCollection();
      $price = $collection->getBasePriceDelivery();
    • without discounts/extra charges
      $shipmentCollection = $order->getShipmentCollection();
      $price = $collection->getBasePriceDelivery();

    Setting a pick-up location for shipment

    $order = \Bitrix\Sale\Order::load(123);
    $collection = $order->getShipmentCollection();
    $shipment = $collection->getItemById(1);
    $storeId = '2';

    Example contains an already existing order. Code is similar for the new order.

    Getting list of available delivery services with account of configured restrictions

    $deliveryList = \Bitrix\Sale\Delivery\Services\Manager::getRestrictedList($shipment, $mode);
    Parameters Description Available from version
    $shipment Shipment object.
    $mode One of two values:
    • \Bitrix\Sale\Services\Base\RestrictionManager::MODE_CLIENT
    • \Bitrix\Sale\Services\Base\RestrictionManager::MODE_MANAGER

    Default: \Bitrix\Sale\Services\Base\RestrictionManager::MODE_CLIENT. Client/customer mode returns list of only delivery services, meeting the restrictions.

    Manager mode returns full list of delivery services (deliveries, not falling under restrictions, have the key RESTRICTED).

    © «Bitrix24», 2001-2024