Craft Picqer plugin documentation

Commerce Picqer Plugin for Craft CMS, official version by WHITE Digital Agency

Back to the Picqer plugin page

Requirements

This plugin requires Craft CMS 3.4 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)
A valid Picqer account is required.
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 Picqer 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-picqer
Install the plugin via ./craft plugin/install commerce-picqer via the CLI

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

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 Picqer setup in Craft.

Connect Craft to your Picqer account

Provide your Picqer API Subdomain and API Key in the General settings tab (other tabs are going to be disabled until you do so). You can create API keys in your Picqer control panel in the Settings → API Keys section.

Exporting orders from Craft to Picqer

If you wish to automatically push orders from Craft to Picqer, you can enable this feature by navigating to the “Craft to Picqer” tab in the plugin settings. This step is completely optional: if you only want to import Picqer data into Craft, you can skip this step.

To enable or disable Craft to Picqer export completely, you can use the “Push orders to Picqer”.
You can select orders of which status will be automatically pushed to Picqer in the “Order Status to push orders”. When a Craft Commerce order with one of the specified statuses gets saved, it will be automatically pushed to Picqer as a concept order.
Additionally, you can let Craft push product prices along with the order (overriding the default prices of each product configured in Picqer), or create missing products in Picqer automatically by enabling the corresponding checkboxes.
When exporting orders, the Picqer plugin will try to match products in picqer by SKU of a product/variant in Craft and a Product Code in Picqer. If the “Automatically create missing products” option is enabled, Craft will create missing products in Picqer by using SKU as a Product Code, title of the product as a Product Name, and Variant Price as a Price in Picqer. You would have to provide all the additional information that you need manually in the Picqer control panel. Otherwise, Picker API returns an error when you try to create an order with a missing product.
You can also let Craft automatically allocate stock and put the order in Picker to the processing state when an order transitions to one of the specified order statuses. It can also be done in one go, for a single specific order status. When you “allocate stock”, webshop items will be reserved for the corresponding order and deducted from the total stock. “Processing” an order means that it will be finalised and added to a picklist.

Note: Make sure to double check plug-in settings when you apply changes to order statuses; especially when you delete a status or rename a handle.

Importing data from Picqer into Craft

You can automatically pull all product stock changes from Picqer to Craft, or automatically update order statuses in Craft when they get changed in Picqer. To do so, navigate to the “Picqer to Craft” in the plugin settings. This step is also optional: if you only want to export orders from Craft to Picqer, you can skip this step.

Synchronizing product stock with Picqer

Craft can automatically update product stock in Craft when it changes in Picqer by enabling the “Pull product stock” option and registering the webhook.

Screenshot 3 Importing data from Picqer into Craft

Note: It is possible to register webhooks on an environment via the Picqer settings page, even when you lock system settings for a certain environment (e.g. your production server with disabled system settings).

Note: Don’t forget to save the changes by clicking the “Save” button.

Updating Craft order statuses on Picqer order state change

When the order state in Picqer changes, you can make Craft order status change automatically to reflect the change. For example, when Picqer order transitions from the “concept” state to the “processing” state, this plugin can automatically change order status in Craft to the desired one (like “Shipped”); or when the Picqer order gets cancelled, it can set the order status in Craft to “Cancelled” too.

To make this work, first create all desired order statuses in Craft: navigate to Commerce → System Settings → Order Statuses.
Once you configured all possible order statuses, go back to the Picqer plugin settings and configure the “Order status mapping” table: add a row and if you want just direct match between the Picqer order state and Craft order status, leave the first column set to “(Any)” and select Picqer and Craft order statuses from the dropdowns.
If you have a more complex order status flow, the first column of the mapping table may become useful: by selecting a specific order status there the mapping rule will ignore all orders with any other order statuses.
After you configured the mapping, you can enable the “Pull order status” checkbox and register the webhook for it.

Warning! Your website should be publicly accessible in order for the webhooks to work. Picqer servers will contact the webhook endpoint of your website to send notifications about the changes in Picqer. If your website address changes, the webhook will stop working and you would need to register it again.

Note: It is possible to register webhooks on an environment via the Picqer settings page, even when you lock system settings for a certain environment (e.g. your production server with disabled system settings).

Note: Don’t forget to save the changes by clicking the “Save” button.

Note: Make sure to double check plug-in settings when you apply changes to order statuses; especially when you delete a status or rename a handle.

Advanced settings

Fast stock updates

If your project has a lot of products and has a very high stock change rate, enabling the “Pull product stock” option may affect your website performance. If (and only if!) it affects your website, you can enable the “Fast stock updates” option located in the “Advanced” tab of the plugin settings. It will make the plugin to just change the stock value in the database directly, without triggering a complete product save procedure which gets executed normally.

Warning! Enabling this option may interfere with other plugins that work with product stock. Only do this if you’re completely sure you know what you’re doing.

Plugin display name

You can change the display name of the plugin in the system by changing the corresponding option in the “Advanced” tab of the plugin settings. It will rename all plugin mentions in the Craft control panel (except on the “Plugins” section).

Picqer information on the order details page

This plugin adds an additional information panel to the order detail page in Craft control panel.

After the order gets pushed to Picqer, you’ll find some useful information about the order:

Picqer Order ID with a link to the order in the Picqer control panel;
Whether the stock has been allocated in Picker or not;
Whether the order has been set to the Processed state or not;
A link to the public order status page.

Note: Your Craft Commerce version should be 3.2 or higher in order to display this panel.

Troubleshooting

Error messages

This plugin is designed to let Craft work without interruptions of normal order processing flow even when some problems occur with the Picqer integration. It won’t display any error messages to the user. Instead, it outputs all error messages to Craft system logs.

It produces the log messages into the Craft’s logging system marked with a separate category, ‘commercepicqer’. Inspect the application log to find Picqer error messages. Additionally, you can always extract Picqer 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']['commercepicqer'] = [
                        'class' => \craft\log\FileTarget::class,
                        'logFile' => '@storage/logs/commercepicqer.log',
                        'categories' => ['commercepicqer'],
                        //'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/commercepicqer.log',
                            'categories' => ['commercepicqer'],
                            //'levels' => Logger::LEVEL_ERROR | Logger::LEVEL_WARNING,
                            'logVars' => [],
                        ]);
                    }
                ],
            ],
        ]
    ],
];

Webhook failures

When a webhook called by Picqer fails too many times, Picqer may disable it. In this case, you would have to register the webhook again from the plugin settings page.

To find out what caused any problems with the webhook, you can look into the webhook call log in your Picqer control panel located under Settings → Webhooks.

Synchronization issues

When Craft doesn’t receive proper notifications about changes to the order in Picqer (for example, if the webhook stops working due to some incorrect manual actions to the order in Picqer), it may be required to force Craft to “forget” about the order synchronization state.

To do this, you would have to manually delete the corresponding record in the database. You can find them in the 'commercepicqer_ordersyncstatus' table.

Picqer support

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