Royal Mail Service
page last edited on 15 August 2018
X-Cart is integrated with the Royal Mail (the national postal service and courier company in the United Kingdom) via the addon Royal Mail Service.
The Royal Mail integration addon for X-Cart sends the order information to Royal Mail. There it’s given a tracking ID, shipping and customs labels and RM sends them back to your store. After that, you can label the orders and print out the manifest for the courier.
To start working with the addon make sure the Royal Mail Service is installed and enabled as described in Installing Addons from the X-Cart App Store.
Configuring Royal Mail Services
PREREQUISITES: Make sure you’re signed up with Royal Mail. For this purpose:
Create your free API account here.
Make sure to enter a valid email address when registering an account with Royal Mail, as Royal Mail will send you a verification link to activate your account after the registration.
Register your application in the ‘My Apps’ section of your Royal Mail account.
When you register, your application is assigned a unique client ID and client secret. You’ll need these data to configure the Royal Mail addon in your X-cart based store.
Subscribe to a Royal Mail API in your Royal Mail account as it needs an approval by Royal Mail; this usually takes less than a week.
Open the Royal Mail addon settings page (Store setup -> Royal Mail) to configure it:
Here you’ll need to define the following Royal Mail account data:
- Client ID : Specify your Royal Mail client ID
- Client Secret : Specify your Royal Mail passowrd
- API Username : Specify your Royal Mail API username
- API Password : Specify your Royal Mail API password
- Aplication ID : Specify your Royal Mail application ID
- Save API request/response to log file : This option enables logging of requests to the Royal Mail server and responses from it. The logs are saved to RM.log files in the
Submit the configuration settings when you are done.
Then you’ll need to proceed to the Royal Mail Services tab (Store setup -> Royal Mail -> Royal Mail Services) to set up the service relations:
To add a new relation click the Add relation button and select the values from the dropdown fields in the new relation’s line in series:
Save the changes when you are done.
Royal Mail Services doesn’t have an API facilitating online shipping rates calculation. Hence the Royal Mail Services addon cannot be used for calculating online shipping rates at checkout, but only for shipping orders via the Royal Mail Services.
Please make sure you have offline shipping rates configured in conjunction with the Royal Mail rates and relations you set up to offer shipping calculation at checkout to your customers.
Shipping Orders via Royal Mail Services
RM shipment for an order is created automatically on the Royal Mail server when the order gets a PAID payment or a PROCESSING fulfilment statuses. If the order status is changed back to NEW the existing RM shipment is cancelled automatically as well.
After an RM shipment is created, X-Cart sends a request to Royal Mail and receives a tracking number that is automatically assighed to the order and registered on the order details page:
A cart admin can also create an RM Shipment manually by clicking on a green button at the bottom of the order details page:
The green Create PM Shipment button is then changed to red Cancel RM Shipment one, the later becomes unavailable after the order manifest is sent to Royal Mail.
In case the order details change (e.g. the change of shipping address, etc.) RM shipment is updated automatically on the Royal Mail server. Once an order manifest is sent to Royal Mail all shipments get fixed and can’t be changed or cancelled.
To print a label of an order and/or an international document if applicable a cart admin should use the buttons of the same name at the top of the page:
Please note that the “ImageMagick” library is required for proper resizing of shipping labels while printing. In case the “ImageMagick” library is installed the label will be available for printing by clicking the Packing Slip button at the top of the page.
Make sure the “ImageMagick” library is installed on the server hosting your X-Cart store for you.
A shipping label and international document should then be affixed to a shipping container specifing its content:
To send an order manifest to Royal Mail a cart admin should use the Send manifest button opposite the order in question in the Orders -> Royal Mail Manifests section:
After a manifest is sent it’s not possible to change the shipping data and cancel the RM shipment for the order.
Then the store admin should print off a Royal Mail manifest using the Print manifest button opposite the order in question in the Orders -> Royal Mail Manifests section and handover it with a shipping container:
Help make this document better
This guide, as well as the rest of our docs, are open-source and available on GitHub.