Shipments

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:

• 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())
  {
  	var_dump($item);
  }
  

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);
  
  $collection->addItem($shipment);
  

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
"DATE_CANCELED",
"EMP_CANCELED_ID",
'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())
  {
  	var_dump($r->getErrorMessages());
  }
  

• Delivery is denied

  $r = $shipment->disallowDelivery();
  if (!$r->isSuccess())
  {
  	var_dump($r->getErrorMessages());
  }
  

Managing shipped delivery flag

• Delivery shipped

  $r = $shipment->setField('DEDUCTED', 'Y');
  if (!$r->isSuccess())
  {
  	var_dump($r->getErrorMessages());
  }
  

• Delivery not shipped

  $r = $shipment->setField('DEDUCTED', 'N');
  if (!$r->isSuccess())
  {
  	var_dump($r->getErrorMessages());
  }
  

Updating delivery cost

$price = 123;
$shipment->setBasePriceDelivery($price);

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';
$shipment->setStoreId($storeId);
    
$order->save();

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);