Extending Sendcloud
The Sendcloud plugin exposes several Craft events so you can customize payloads before orders are pushed or labels are created.
# Register event listeners
Register listeners from your custom module init() method (or another place that runs on every request where you need the listener):
<?php
namespace modules\site;
use yii\base\Module;
use yii\base\Event;
use white\commerce\sendcloud\services\OrderSync;
use white\commerce\sendcloud\services\OrderItems;
use white\commerce\sendcloud\events\AddressEvent;
use white\commerce\sendcloud\events\OrderDetailsEvent;
use white\commerce\sendcloud\events\OrderItemEvent;
use white\commerce\sendcloud\events\ValidateOrderEvent;
class SiteModule extends Module
{
public function init(): void
{
parent::init();
Event::on(OrderSync::class, OrderSync::EVENT_AFTER_CREATE_ADDRESS, static function(AddressEvent $event): void {
// ...
});
Event::on(OrderSync::class, OrderSync::EVENT_CREATE_ORDER_DETAILS, static function(OrderDetailsEvent $event): void {
// ...
});
Event::on(OrderItems::class, OrderItems::EVENT_CREATE_ORDER_ITEM, static function(OrderItemEvent $event): void {
// ...
});
Event::on(OrderSync::class, OrderSync::EVENT_AFTER_VALIDATE_ORDER, static function(ValidateOrderEvent $event): void {
// ...
});
}
}
# Available events
# OrderSync::EVENT_AFTER_CREATE_ADDRESS
Triggered after a Sendcloud address model is created from a Craft address.
- Event class:
white\commerce\sendcloud\events\AddressEvent - Properties:
$event->craftAddress(craft\elements\Address)$event->sendcloudAddress(white\commerce\sendcloud\models\Address)
Example (map house number from addressLine2):
Event::on(OrderSync::class, OrderSync::EVENT_AFTER_CREATE_ADDRESS, static function(AddressEvent $event): void {
$event->sendcloudAddress->setHouseNumber($event->craftAddress->addressLine2);
$event->sendcloudAddress->setAddressLine2(null);
});
# OrderSync::EVENT_CREATE_ORDER_DETAILS
Triggered when the Sendcloud order details payload is built.
- Event class:
white\commerce\sendcloud\events\OrderDetailsEvent - Properties:
$event->order(craft\commerce\elements\Order)$event->orderDetails(white\commerce\sendcloud\models\OrderDetails)
Example (override status data sent to Sendcloud):
Event::on(OrderSync::class, OrderSync::EVENT_CREATE_ORDER_DETAILS, static function(OrderDetailsEvent $event): void {
$event->orderDetails->setStatus([
'code' => $event->order->orderStatus->handle,
'message' => $event->order->orderStatus->description ?: 'Updated by custom module',
]);
});
# OrderItems::EVENT_CREATE_ORDER_ITEM
Triggered for each line item that is converted into a Sendcloud order item.
- Event class:
white\commerce\sendcloud\events\OrderItemEvent - Properties:
$event->lineItem(craft\commerce\models\LineItem)$event->orderItem(white\commerce\sendcloud\models\OrderItem)
Example (append SKU to the exported item name):
Event::on(OrderItems::class, OrderItems::EVENT_CREATE_ORDER_ITEM, static function(OrderItemEvent $event): void {
$sku = $event->lineItem->getSku();
if (!empty($sku)) {
$event->orderItem->setName($event->orderItem->getName() . ' [' . $sku . ']');
}
});
# OrderSync::EVENT_AFTER_VALIDATE_ORDER
Triggered after the plugin validates whether an order can be synced.
- Event class:
white\commerce\sendcloud\events\ValidateOrderEvent - Properties:
$event->order(craft\commerce\elements\Order)$event->isValid(bool)
Example (log failed validations for debugging):
use Craft;
Event::on(OrderSync::class, OrderSync::EVENT_AFTER_VALIDATE_ORDER, static function(ValidateOrderEvent $event): void {
$event->isValid = $event->order->shippingMethodHandle !== 'pickup'; // prevent syncing pickup orders
});