Royal Mail Shipping (Beta)

Send Magento orders to Royal Mail Click & Drop, get the PDF label and the tracking number back, offer Royal Mail services at checkout with flat, table or live prices, cancel labels and create Tracked Returns labels. This package is a carrier for Shipping Connect (softaware/module-shipping-core, free), which provides the checkout methods, label printing, returns and the API log.

• Admin demo (all Shipping Connect carriers): https://demo.softawarecommerce.com/try-admin/shipping
• Changelog: Release notes · Questions: FAQ

The demo connections have no credentials and are switched off, so the demo shows the admin screens and example labels but does not contact Royal Mail.

Status: Beta. Written from the public Click & Drop API specification and tested with recorded responses, as Royal Mail offers no test system. Test with your own account before going live.

1. Requirements

A Royal Mail business account is required. The module talks to the Click & Drop API (api.parcel.royalmail.com, version 1) with the API key from your Click & Drop account. It does not use the Royal Mail Shipping API v2 or the Royal Mail Tracking API.

2. Installation

With Composer. Use the Composer keys from your account on softawarecommerce.com (see https://softawarecommerce.com/shop/composer-access/):

composer config repositories.softaware composer https://repo.softawarecommerce.com
composer config --auth http-basic.repo.softawarecommerce.com PUBLIC_KEY PRIVATE_KEY
composer require softaware/module-shipping-royalmail
bin/magento setup:upgrade
bin/magento setup:di:compile            # production mode only
bin/magento setup:static-content:deploy # production mode only
bin/magento cache:flush

Shipping Core is installed with it. To update later: composer update softaware/module-shipping-royalmail, then the same bin/magento commands.

3. Quick start

1. In Click & Drop: Settings > Integrations > Click & Drop API, copy the API key.
2. In Magento: Stores > Configuration > Softaware > Shipping Connect > General > Enabled = Yes.
3. Softaware > Shipping Connect > Carrier Connections > Add Carrier Connection, choose Royal Mail Click & Drop.
4. Enter a Name, switch Enabled on, choose the Website. Leave Sandbox / Test Mode off: Royal Mail has no test system.
5. Paste the API Key and click Test Connection ("Royal Mail Click & Drop accepted the API key.").
6. Under Carrier Settings choose the Account Type and Package Format.
7. Add checkout methods, for example "Royal Mail Tracked 24" and "Royal Mail Tracked 48", fill in the Sender Address and Parcel Defaults and click Save.

4. The Royal Mail connection in detail

General

Credentials

The key is stored encrypted and never shown again; leave ****** to keep the saved value. Test Connection reads one order from Click & Drop with the key in the form, without saving it.

Carrier Settings

Checkout Methods

Each row is a home delivery method at checkout with a Title, a Carrier Product (Royal Mail service), a Price, Free From Subtotal, Countries (ISO codes) and Sort.

Royal Mail services in this package:

Which services Click & Drop accepts depends on your Royal Mail account.

Price options:

• Flat, or by weight or subtotal with a price table such as 2:4.95, 5:6.95, 31.5:9.95 (above the last limit the method is not offered).
• Live carrier price: the module asks Click & Drop for the price of the service for the destination country, postcode, weight and package format and adds VAT. Royal Mail quotes in pounds, so live prices are used only when the base currency is GBP; otherwise, or when no price comes back, the Flat / Fallback Price applies.

Cart rules with free shipping make every method free. Royal Mail methods are home delivery only; there are no pickup points for this carrier.

Sender Address and Parcel Defaults

The sender's trading name (company, or contact name), phone and e-mail are sent with the order; the sender address can also come from an MSI inventory source. Parcel defaults (weight in kg, length, width and height in cm) pre-fill the label form. Dimensions are sent in millimetres.

5. Creating labels

One order: open the order and click Create Shipment and Label. Several orders: select them in the order grid and choose Create Shipments and Labels (up to 50 orders at a time). Check the connection, the Royal Mail service, the number of parcels, the weight per parcel and the dimensions, then create the labels.

What happens:

1. The order goes to Click & Drop with the recipient, the packages, the order total and the chosen service. Royal Mail sends its delivery notifications to the recipient's e-mail address when one is known.
2. With an Online Business Account the PDF label comes back in the response. For addresses outside the UK the module asks for the customs form on the label.
3. Click & Drop returns a tracking number per package; the module creates the Magento shipment with the tracking numbers (or adds the label to an existing shipment) and can send the shipment e-mail.
4. With pay as you go, or when Click & Drop reports a label error, the order is still created and Magento shows "Order created in Click & Drop; print the label there." with Royal Mail's message.

Print All Labels gives one merged PDF; Print Shipping Connect Labels in the order grid prints the labels of the selected orders. A label is never created twice by accident: the order is locked while the label is created, and a request that may have reached Royal Mail is not repeated.

Cancelling

Cancel in the order view or on the label page (permission "Cancel Labels") deletes the order in Click & Drop. Do this before the parcel is handed over.

6. Tracking

The tracking number is stored on the Magento shipment, so it appears in the shipment e-mail, the customer's order view and Magento's tracking pop-up, which links to the Royal Mail tracking page. Tracking events and delivery dates are not fetched for Royal Mail: they need the separate Royal Mail Tracking API, which this package does not use, so the tracking cron skips Royal Mail labels.

7. Return labels

With an Online Business Account, Create Return Label in the order view books a Royal Mail Tracked Returns label (service from Return Service Code) from the customer's address back to your sender address. The PDF is stored like any label, and the label page has a signed download link (30 days) you can send to the customer. Softaware Returns can create the same return labels from its return page.

8. Command line

bin/magento softaware:shipping:adapters                       # installed carriers and what they support
bin/magento softaware:shipping:test-connection [connection id] # test the API key
bin/magento softaware:shipping:create-label <order number> [-c connection] [-s TPN24] [-p parcels] [-w kg] [--return] [--no-email]

9. Permissions (ACL)

Under Softaware > Shipping Connect: View Shipments and Labels, Create Shipments and Labels, Cancel Labels, Create Return Labels, Manage Carrier Connections, View API Log, Settings. Creating labels also needs Sales > Operations > Orders > Actions > Ship.

10. Data sent to Royal Mail

Recipient name, company, address, phone and e-mail (delivery notifications), sender trading name, phone and e-mail, parcel weights and sizes, the order number, the order subtotal and total. Price lookups send the destination country, postcode, weight and package format. Every request is written to Softaware > Shipping Connect > API Log with the API key masked.

11. Limits and troubleshooting

• Click & Drop allows 5 requests per second; mass label creation of many orders takes a moment.
• No test system: create a real order, check it in Click & Drop and cancel it.

12. Uninstall

bin/magento module:disable Softaware_ShippingRoyalmail
composer remove softaware/module-shipping-royalmail
bin/magento setup:upgrade

Existing labels stay in Shipping Core's tables; Royal Mail connections can no longer be used until the package is installed again.