Skip to content
  • Documentation >
  • Commerce >
  • Shipping management >
  • Shipment API

Shipment API

To get shipments and manage them, use the Ibexa\Contracts\Shipping\ShipmentServiceInterface interface.

From the developer's perspective, shipments are referenced with a UUID identifier.

Get single shipment

Get single shipment by identifier

To access a single shipment by using its string identifier, use the ShipmentService::getShipmentByIdentifier method:

1
2
3
4
5
6
7
8
9
$identifier = '4ac4b8a0-eed8-496d-87d9-32a960a10629';
$shipment = $this->shipmentService->getShipmentByIdentifier($identifier);

$output->writeln(
    sprintf(
        'Your shipment has status %s',
        $shipment->getStatus()
    )
);

Get single shipment by id

To access a single shipment by using its numerical id, use the ShipmentService::getShipment method:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
$id = 1;
$shipment = $this->shipmentService->getShipment($id);

$output->writeln(
    sprintf(
        'Shipment %d has status %s',
        $id,
        $shipment->getStatus()
    )
);

Get multiple shipments

To fetch multiple shipments, use the ShipmentService::findShipments method. It follows the same search query pattern as other APIs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
$shipmentCriteria = [
    new ShippingMethod($this->shippingMethodService->getShippingMethod('free')),
    new CreatedAt(new \DateTime('2023-03-24 15:09:16')),
    new UpdatedAt(new \DateTime('2023-03-25 09:00:15')),
];

$shipmentQuery = new ShipmentQuery(new LogicalOr(...$shipmentCriteria));
$shipmentQuery->setLimit(20);

$shipmentsList = $this->shipmentService->findShipments($shipmentQuery);

$shipmentsList->getShipments();
$shipmentsList->getTotalCount();

foreach ($shipmentsList as $shipment) {
    $output->writeln(
        $shipment->getIdentifier() . ': ' . $shipment->getStatus()
    );
}

Create shipment

To create a shipment, use the ShipmentService::createShipment method and provide it with an Ibexa\Contracts\Shipping\Value\ShipmentCreateStruct object that takes two parameters, a shippingMethod string and a Money object.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
$shipmentCreateStruct = new ShipmentCreateStruct(
    $this->shippingMethodService->getShippingMethod('free'),
    $this->orderService->getOrder(135),
    new Money\Money(100, new Money\Currency('EUR'))
);

$shipment = $this->shipmentService->createShipment($shipmentCreateStruct);

$output->writeln(
    sprintf(
        'Created shipment with identifier %s',
        $shipment->getIdentifier()
    )
);

Update shipment

You can update the shipment after it's created. You could do it to support a scenario when, for example, the shipment is processed offline and its status has to be updated in the system. To update shipment information, use the ShipmentService::updateShipment method:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
$shipmentUpdateStruct = new ShipmentUpdateStruct();
$shipmentUpdateStruct->setTransition('send');

$this->shipmentService->updateShipment($shipment, $shipmentUpdateStruct);

$output->writeln(
    sprintf(
        'Changed shipment status to %s',
        $shipment->getStatus()
    )
);

Delete shipment

To delete a shipment from the system, use the ShipmentService::deleteShipment method:

1
$this->shipmentService->deleteShipment($shipment);