Craft Commerce integration

Purpose: Learn how to connect your Craft web shop with your Sendcloud account.

Requirements

• This plugin requires Craft CMS 3.3 or later
• This plugin requires Craft Commerce version 3.1 or later (version 3.2 or higher is required to display the side panel on the order page)
• 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. Click hereto access settings. 
• The plugin should be able to create a custom table in your database
  
• This plugin is compatible with Composer 2.0

Step 1: Install the Sendcloud plugin 

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

1. Open your terminal and go to your Craft project:
   

   cd /path/to/project

2. Then tell Composer to load the plugin:
   

   composer require white-nl/craft-commercesendcloud

3. Install the plugin via the CLI:
   

    ./craft install/plugin commercesendcloud 

Step 2: 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.

Step 3: Basic setup

After installing, open the plugin settings page in your Craft project to complete the setup of Sendcloud in Craft. 

1. Connect Craft with Sendcloud
   Make sure your Craft website is accessible by Sendcloud servers. Then click Register 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 in Craft (you may have to reload the page to see the changes).
   
   
   
2. Create shipping methods
   The next step is to create shipping methods for Sendcloud in Craft. The list below the connection status shows 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 your Sendcloud shipping method. You also have to configure shipping rules for the newly created shipping method for it to appear on the frontend.
   
   
   
3. Select order status for pushing to Sendcloud
   In the Order Sync tab in the Sendcloud plugin settings, 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 can't be sent to Sendcloud before a shipping label is created. If you push an order through to Sendcloud before creating the shipping label, the order will appear in Sendcloud with the default shipping method pre-selected. 
   
   If you prefer to create labels automatically at the point where an order transitions to a specific order status, you can so by selecting the status in the "Create labels for orders" option. Before creating a label, the plugin will automatically ensure that the order is correctly pushed through to Sendcloud. 
   
   
4. Map Sendcloud parcel statuses to Craft order statuses
   If you want to automatically update the order status in Craft according to the Sendcloud parcel status, map specific Sendcloud parcel status to a Craft order status. Order statuses 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 be updated.
   
   
   
5. Decide whether the integration should use the Craft order number or the order ID
   If you work with different mappings and other systems apart from Sendcloud and Craft, having the option to choose between these two gives you more flexibility.
   
   
6. Save the plugin settings in Craft
   Click the red Save button when you're finished. 

Download shipping labels

After completing setup, new orders with the order status you have selected will be pushed to Sendcloud and the shipping labels will automatically be created for you. There are two ways to download shipping labels in Craft -  multiple labels at once, or a single label at a time.

1. Commerce order overview page
   Use the check boxes to select one or more orders. Click Print Sendcloud Labels in the options menu. The resulting PDF file will contain labels for all selected orders.
   
   
   
2. Commerce order details page
   Open a 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 an order which does not yet have a shipping label created in Sendcloud, a new label will automatically be created for you. 
   

Pushing orders manually

It's also possible to manually push an order through 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.

1. Commerce order overview page
   Use the check boxes to select one or more orders, then select Push to Sendcloudin the options menu.
   
   When pushing a number of orders at one time, the webserver may kill the request, resulting in a request timeout error. We recommend that you don't attempt to push more than 50 orders at a time. Rather, it's preferred to configure automatic order pushing by status (see previous steps). 
   
   
   
2. Commerce order details page
   If the order is not yet pushed to Sendcloud, you will see 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 an order manually to Sendcloud, a shipping label is not created automatically. A label will only be created when you first attempt to print a label. The shipping method and address will not be pushed to Sendcloud unless you create a shipping label, therefore your order will appear with the default shipping method pre-selected. 

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 of the Sendcloud 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:

1. Enable Service Points in Sendcloud
   To set up service point (or pickup point 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.
   • To enable service points in Sendcloud, log in to your account and navigate to Settings > Integrations. 
   • Find your Craft Commerce integration in the list of connected integrations and click Configure.
   • Next, tick the option Service Points to enable the service point feature, and choose the carries you want to offer for service point delivery.
   • Click Save when you're done. 
     
     
     
2. Create Service Point shipping method in Craft
   After enabling Service Points in Sendcloud, the plugin settings page will showe the enabled status for shipping points (green) and the list with available shipping methods will display the methods for service point shipping.
   To create a Craft shipping method, click the plus (+) button. You can also 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 in order for it to appear on the frontend.
   
   
   
3. 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. 
   
   

Our example template does the following:

• It displays the Select Service Point button for shipping methods with service points enabled.
• 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.
• 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.

Shipping outside Europe (optional)

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

Make sure you have custom fields containing HS Code and Country Of Origin configured for products or variants in Craft. Next, 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.

Display Sendcloud order information on the frontend (optional)

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

• Display order 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 last order error

If an order is not correctly pushed to Sendcloud, you can view the error message for the latest order to see why an error has occurred. In Craft, you can select the Sendcloud tab on the order details page. click the ℹ️ icon to see the full message text. 

Issues when pushing orders and creating labels

If the Sendcloud plugin fails to push an order through to Sendcloud, or to create a shipping label, you can view the last error related to the failed order by going to the order edit page in the Sendcloud tab in the sidebar panel. 

It is often the case that an order fails to sync because some of the data inside of the order is invalid. You must ensure, for example, that customer address data (address lines/phone number fields and postcode fields, etc.) is properly captured and validated on your checkout page. If a field contains characters which exceeds the character limits, or if unrecognised symbols or characters are present, an error will occur.

In the example above, you can see that the order is in error as the HS Code field has too many characters entered. 

In the case of international shipments, ensure that the HS Code and Country of Origin fields (if enabled) contain valid data, and that your shipping methods are properly configured. For example, ensure that the service point picker is enabled if you offer the option to have parcels delivered to a service point. 

Once you've resolved any issues related to an order, you can try to manually push it through to Sendcloud once again by clicking the corresponding button in the order details page. 

Error logging

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

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

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' => ['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. You can do this by navigating to Settings > Integrations in your Sendcloud account, and clicking the Disconnect button under your Craft webshop connection.

When you disconnect the integration in Sendcloud, the connection will also still be active in Craft. You also have to disconnect the integration manually in Craft. 

Sendcloud order canceling

When an order is canceled in Sendcloud, the Craft webhook will be triggered and the Sendcloud data will also be deleted in the plugin’s custom table. This will show the Push to Sendcloud button on the order detail page again. The cancelation of orders in Sendcloud can slightly delayed, so as long as the Sendcloud parcel status is “Cancelation requested”, the order will not be deleted from the custom table.

For more help, you can consult the Craft CMS documentation manual, or log a ticket via the support section of your Sendcloud account.