Craft Sendcloud plugin documentation

Sendcloud plugin for Craft CMS, official version by WHITE Digital Agency

Back to the Sendcloud plugin page

Requirements

For Craft CMS 3.4+ with Commerce 3.1+ use 1.x of this plugin
For Craft CMS 4.0+ with Commerce 4.0+, use 3.x of this plugin
This plugin shows a side panel on the order page on Craft Commerce 3.2+
A valid Sendcloud account is required. Don't have an account yet? Create a Sendcloud account.
The Craft website should be publicly accessible
To configure the plugin, changing settings should be allowed in Craft (allow admin changes), and a user who is an Admin in Craft.
The plugin should be able to create a custom table in your database
This plugin is compatible with Composer 2.0

Installation

To install Sendcloud plugin for Craft CMS, follow these steps:

Open your terminal and go to your Craft project:
cd /path/to/project
Then tell Composer to load the plugin:
composer require white-nl/commerce-sendcloud
Install the plugin via ./craft plugin/install commerce-sendcloud via the CLI

You can also install the Sendcloud plugin using the Plugin Store in the Craft Control Panel. Go to Settings → Plugins and click the “Install” button for Commerce Sendcloud.

Activate your license

This plugin requires a commercial license. After successfully installing the plugin, you’ll see an alert bar in Craft. Click this bar to activate your license in the Craft plugin store using your Craft ID.

Basic setup

After installing, open the plugin’s settings page in your Craft project to do the actual Sendcloud setup in Craft.

Connect Craft with Sendcloud
Make sure your Craft website is accessible by the Sendcloud servers. Then use the Register button to connect with Sendcloud. You will be redirected to the Sendcloud website and asked to confirm the integration. After setting up a connection the connection status should be Active (you may have to reload the page to see the changes)
Create shipping methods
Next step is to create the Shipping methods for Sendcloud in Craft. The list below the connection status is showing all available Sendcloud shipping methods for enabled countries in Craft Commerce store settings. If you can’t see some of the shipping methods please make sure you have corresponding countries enabled in Craft Commerce. To create a Commerce shipping method click the plus (+) button or manually create a shipping method with the exact same name as the Sendcloud shipping method! You also have to configure shipping rules for the newly created shipping method for it to appear on the frontend.
Select order status for pushing to Sendcloud
On the plugin settings Order Sync tab select the Craft order status for the orders you want to be automatically pushed to Sendcloud. (You can select more than one)

Please note that the shipping method could not be sent to Sendcloud before you create a label. If you just push the order without creating a label, the order in Sendcloud will end up with the default shippingmethod.

If you wish to create labels automatically when an order transitions to a specific order status, you can do so by selecting the status in the “Create labels for orders” option.
Map Sendcloud parcel statuses to Craft order statuses
If you wish to automatically update order status in Craft according to Sendcloud parcel status, map specific Sendcloud parcel status to a Craft order status. Order status will be updated automatically when the parcel status changes. When Craft receives an unmapped parcel status it will be ignored. If you don't assign any status then no orders will ever be updated.
Don’t forget to save the plugin settings in Craft

There are more optional things to set up, but this is the basic stuff you have to do. Now you can test this integration by creating a test order in your project and check your Sendcloud account to see your test order.

Download shipping labels

After finishing the setup, orders will be pushed and labels will be created automatically in Sendcloud according to the order statuses configured in the previous step. There are two ways to download shipping labels in Craft: Multiple labels at once or a single label at a time.

Commerce order overview page
Use the check boxes to select one or more orders and click “Print Sendcloud Labels” in the options menu. The resulting PDF file will contain labels for all selected orders.

When you try to print a label for an order that hasn't been pushed to Sendcloud yet, it will be pushed and a label will be created automatically for you before printing the label.

When creating a lot of labels at once, your webserver may kill the request, resulting in the request timeout errors. It's not recommended to create more than 20 labels at once. It's better to configure automatic label creation by status (see previous steps) instead and use the "Print Sendcloud Labels" only for printing out already created labels.
Commerce order details page
Open specific order in Craft. You will find the Sendcloud information panel in the right sidebar (available only on Craft Commerce versions 3.2 or higher). Click the Print Label button. The resulting PDF file will contain labels for the selected order.

If you try to print a label for the order that doesn't have a label created in Sendcloud, a new label will be automatically created for you.

Pushing orders manually

It is always possible to do a manual order push to Sendcloud. This can be useful when you have an order with a different status, or when the order is not pushed for some reason. There are two ways to do an order push to Sendcloud: Multiple orders at once or a single order.

Commerce order overview page
Use the check boxes to select one or more orders and “Push to Sendcloud” in the options menu.

When pushing a lot of orders at once, your webserver may kill the request, resulting in the request timeout errors. It's not recommended to push more than 50 orders at once. It's better to configure automatic order pushing by status (see previous steps) instead.
Commerce order details page
If the order is not yet pushed to Sendcloud, you will find the Push to Sendcloud button (available in Craft Commerce versions 3.2 or higher). After pushing, additional Sendcloud information and a button to download the label will become available.

Please note that when you push orders manually, no label will be created automatically. A label will be created only when you first try to print a label. Shipping method and address doesn't get pushed to Sendcloud unless you create a label so your order will end up with the default shipping method.

Service Point shipping (optional)

This plugin supports Sendcloud Service Point shipping. This is a more complex set up and custom development is required to integrate the service point checker in your webshop's checkout page. Because every Craft project can have a different front-end stack, template code and approach this plugin only contains an example for the Sendcloud’s service point picker for the default Craft Commerce demo shop frontend templates. After installing you will find a drop-in replacement for the shipping template of Craft Commerce in the `example-templates` folder. Simply copy and paste this into your `templates` folder. After that, follow this setup procedure:

Enable Service Points in Sendcloud
To set up service point (or pickuppoint shipping) in Craft, first make sure you have Service Points enabled in Sendcloud and select the carriers you want to show in the service point picker.
Create Service Point shipping method in Craft
After enabling Service Points in Sendcloud the plugin settings page shows the enabled status for Shipping points (green) and the list with available shipping methods is showing the methods for service point shipping. To create a Commerce shipping method click the plus (+) button. Or manually create a shipping method with the exact same name as the Sendcloud shopping method! You also have to configure shipping rules for the newly created shipping method for it to appear on the frontend.
Integrate Service Point picker into your front-end
If you’re using default Craft Commerce demo shop templates, you can simply copy the templates from our plugin’s `example-templates` folder into your website’s `templates` folder. Otherwise, you would have to implement the service point picker functionality by yourself.

Our example template does the following:
1. It displays the Select Service Point button for shipping methods with service points enabled.
2. When you click on the button, a Sendcloud service point selection iframe will pop up. Service points will be filtered out by the carrier of the selected shipping method and selected shipping address.
3. After you select the service point, it will be displayed on the frontend and a background AJAX request will be sent to the Sendcloud plugin to store the selected information.
When you push the order (or when it gets pushed automatically), the selected service point will be used.

Some shipping methods may require a valid phone number. Sendcloud’s API will reject an order that contains invalid shipping information, so make sure you build a good validation!

Please keep in mind that the example from the `example-templates` folder is for demonstration purposes only. It’s your responsibility to build a front-end with a proper validation for your shop!

WHITE does not support front-end Service Point picker integrations.

Shipping outside Europe (optional)

This plugin supports Sendcloud Customs documents generation for shipping outside the EU. Use the field mapping in plugin settings to map your existing product fields to the fields needed to generate the Customs documents.

To make it work, make sure you have custom fields containing HS Code and Country Of Origin configured for product or variant in Craft. After that you can select corresponding fields in the Sendcloud plugin settings:

Please make sure that the Country Of Origin field contains only ISO2 Country code (for example, “NL”) and the HS Code plugin contains a valid HS Code of the product (for example, “6403919600”).

When the order is pushed to Sendcloud, the plugin will first search for the fields on the variant level, then on the product level. If any of the fields are empty or missing, the Sendcloud plugin will simply ignore them and push the order without the international shipping information.

Customize the Address data (v3+)

Since version 3 of the plugin the address data is now mapped with the corresponding Craft fields. If you are still using addressLine2 for the houseNumber, you have to manipulate the data via the custom event in your module:

Event::on(JouwWebSendcloudAdapter::class,
    JouwWebSendcloudAdapter::EVENT_AFTER_CREATE_ADDRESS,
    static function (AddressEvent $event): void {
        $address = $event->address;
        $shippingAddress = $event->shippingAddress;

        $address->setHouseNumber($shippingAddress->addressLine2);
        $address->setAddressLine2();
    }
);

Display Sendcloud order information on the frontend (optional)

The Sendcloud plugin provides additional Twig API that can be used on your frontend to:

Display order’s Sendcloud status and service point information.
Display Tracking number and Tracking URL.
Display Return portal URL.

See the variables/SendcloudVariable.php file for more information.

Advanced settings (optional)

Change the plugin’s display name in Craft
If you wish to change the display name of the plugin in Craft, you can do so in the Advanced tab of the plugin settings.

Troubleshooting

Display of last order error

When the Sendcloud plugin fails to push order data to Sendcloud, you will be able to see the latest error (occurred) message in the Sendcloud panel on the order details page. You can click the 'i' icon to see the full message text.

Error during push from Sendcloud to Craft

Problems with pushing orders and creating labels

When the plugin fails to push an order to Sendcloud or create a label, you will be able to see the last error related to the order on the order edit page in the Sendcloud sidebar panel. One frequent problem can be invalid data inside the order. You have to make sure that all the data that comes from the users (address/phone fields for example) is validated properly on your checkout page and no fields exceed Sendcloud limitations. Also make sure the HS code and country of origin fields (if enabled) contain valid data and your shipping methods are configured properly (for example, service point picker is required for every service point shipping method). After you've resolved any problems with an order, you can try to push it again manually by clicking the corresponding button on the order details page.

Error logging

This plugin produces its logs into the Craft’s logging system marked with a separate category, ‘commerce-sendcloud’. Inspect the application log to find Sendcloud error messages. Additionally, for Craft 3, you can always extract Sendcloud log messages into a separate log target. To make it work, you can configure your `config/app.php` file like this:

Craft 3.x

return [ 
	'*' => [ 
		'components' => [ 
			'log' => function() { 
				$config = craft\helpers\App::logConfig(); 
				if ($config) { 
					$config['targets']['commerce-sendcloud'] = [ 
						'class' => \craft\log\FileTarget::class, 
						'logFile' => '@storage/logs/sendcloud.log', 
						'categories' => ['commerce-sendcloud'], 
						//'levels' => Logger::LEVEL_ERROR | Logger::LEVEL_WARNING, 'logVars' => [], 
					]; 
				} 
				return $config ? Craft::createObject($config) : null; 
			}, 
		] 
	] 
];

Craft 3.6+

return [
    '*' => [
        'components' => [
            'log' => [
                'targets' => [
                    '__fileTarget' => function() {
                        if (!class_exists(FileTarget::class)) {
                            return null;
                        }
                        return Craft::createObject([
                            'class' => FileTarget::class,
                            'logFile' => '@storage/logs/sendcloud.log',
                            'categories' => ['commerce-sendcloud'],
                            //'levels' => Logger::LEVEL_ERROR | Logger::LEVEL_WARNING,
                            'logVars' => [],
                        ]);
                    }
                ],
            ],
        ]
    ],
];

Connection issues

When you use the Craft plugin settings to disconnect from Sendcloud the integration will still be active in Sendcloud. You have to disconnect the integration manually in Sendcloud too.

Also the other way around, when you disconnect the integration in Sendcloud the connection will still be active in Craft. You have to disconnect the integration manually in Craft too.

Sendcloud order cancelling

When an order is cancelled in Sendcloud, the Craft webhook will be triggered and the Sendcloud data will be deleted in the plugin’s custom table too. The cancellation of orders in Sendcloud can be a bit delayed, so as long as the Sendcloud status is “Cancellation requested” the order will not be deleted from the custom table.

Sendcloud support

Contact Sendcloud if you have questions about the plugin and the configuration of Sendcloud dashboard.