Royal Mail

Royal Mail offers domestic and international shipping services for shipments originating in Great Britain. ShipStation API's integration with Royal Mail allows our UK-based customers with a Royal Mail Online Business Account - OBA to create domestic and international shipping labels for small parcels to be delivered anywhere within Royal Mail's extensive delivery network.

This guide provides developers with the details needed to build Royal Mail shipping capabilities into your ShipStation API workflows.

Requirements

Connection Requirements

Your Royal Mail account must be an OBA account. Non-OBA accounts are not currently eligible to connect to ShipStation API.

Shipping Requirements

Connect Account

You can connect a Royal Mail account using the POST method to the /v1/connections/carriers/ endpoint, or via the ShipStation API Dashboard.

The Royal Mail connection process involves several manual steps. Once submitted, the connection request notifies both ShipStation and Royal Mail. Your Royal Mail account will remain in an inactive pending state until Royal Mail sends ShipStation your validated OBA credentials, at which time your ShipStation API account will be configured to use Royal Mail services.

Personalized tracking numbers:

The credential verification process and the tracking range request process may take up to 5 business days each.

When your Royal Mail carrier connection is fully activated, you will receive an email notification, a notification in the ShipStation API dashboard, and if you are subscribed, the API_CARRIER_CONNECTED webhook.

Should any errors on the registration form cause Royal Mail to reject the registration request, ShipStation will email you to let you know that corrections are needed. Potential errors could result from your shipping address, OBA email, or Royal Mail account number.

Connect via Endpoint

carrier_name: royal_mail

POST /v1/connections/carriers/:carrier_name

Sample request:

Copy

HTTPcURLJavaScriptNodeJSPHPPythonRubyC#JavaGoSwiftObjective-CPowerShell

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
POST /v1/connections/carriers/royal_mail HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "nickname": "My Royal Mail account",
  "account_number": "123456789",
  "oba_email": "[email protected]",
  "company_name": "Example Corp",
  "contact_name": "John Doe",
  "email": "[email protected]",
  "street_line1": "77 Netherpark Crescent",
  "city": "STIRKOKE HOUSE",
  "postal_code": "KW1 6LZ",
  "phone": "215-555-5555"
  "posting_location_number": "1234567890"
}

A successful connection will return a response with the carrier_id, which you'll use for any requests for this account going forward.

Connect via Dashboard

To connect your Royal Mail account in the ShipStation API dashboard:

Rates

Royal Mail does not send estimated rates to ShipStation API, as Royal Mail does not currently allow third-party apps to connect to their Rates API. Your Royal Mail account contact can provide you with the details about your contracted rates.

Service Details

Available CarrierName services are provided below. Please note that carriers may update their available services at any time. To ensure you are always using valid services, you can use the list carrier services endpoint at any time.

Domestic Services

International Services

Shipping to BFPO Addresses and M Bag Alternative Codes

As of 1st January 2025, Royal Mail removed the HM Forces-specific services. When shipping to BFPO addresses, you should use the available domestic services instead of the now obsolete international codes. You should also apply alternative codes for M Bags where necessary.

Shipping to the Channel Islands

Shipping to Northern Ireland

Starting 1st May 2025, changes to Royal Mail products and services will take effect in accordance with the Windsor Framework. Under the Windsor Framework shipments will fall into 1 of 2 categories:

Royal Mail customers sending parcels from Great Britain to Northern Ireland (GB-NI ) will need to provide additional data. The parcel movement's type will determine what data is required: Business-to-Consumer (B2C), Consumer-to-Consumer (C2C), Consumer-to-Business (C2B), or Business-to-Business (B2B).

Business Accounts - Different Types of Goods Movements

NOTE: For B2B movements, where UKIMS registration is not presented with the parcel data, the sending customer may be liable to delays, customs charges or the parcel returned to the sender.

Consumers - Different Types of Goods Movements

Does Royal Mail offer a Next Day service from Great Britain to Northern Ireland?

Next Day services will be available for C2C, C2B, B2C and B2B. For B2B shipments Royal Mail will only process goods classified as ‘not at risk’. For goods classified as ‘at risk’ Royal Mail may be able to carry these goods on a Parcelforce Worldwide service. For account enquiries contact 03448 429102.

Return Services

To create return labels, Royal Mail must approve you for at least one of the following services:

Both of these return services support labelless shipping. Review our Paperless Labels guide for details on creating paperless labels with ShipStation API.

Review the Return Shipping Labels page for details on creating return labels with ShipStation API.

Packages

The following carrier package types are available for Royal Mail services:

Adding Shipment Insurance

Royal Mail does not support adding carrier insurance.

Label Support

Label Reference Fields

Multi-Package Labels

Multi-package shipping is not supported with Royal Mail.

Voiding Labels

Royal Mail supports voiding labels with ShipStation API. Labels cannot be voided once the shipments have been manifested. If you need to void a shipment on a sales order summary, you must contact Royal Mail directly.

See our Void a Label page for details about voiding labels with ShipStation API.

Paperless Labels

Royal Mail supports paperless labels for the following services:

Add the paperless or label_and_paperless value to the display_scheme property to receive a paperless label download.

See our Paperless Labels page for details about creating paperless labels with ShipStation API.

Customs Declarations

Customs forms will print with the label for your international shipments.

Delivery Confirmation

Royal Mail shipments do not set a default confirmation type.

Royal Mail has enhancement codes that correspond to delivery confirmation types in ShipStation API. For example, the Royal Mail enhancement code for the Signed For service maps to the confirmation type direct_signature.

Only certain services allow certain enhancements. If you choose an option that is not supported with a selected service, you’ll get a generic error like Error code E0004 - Failed Schema Validation.

Please consult with Royal Mail for the latest version of Key FAQs for Royal Mail API Shipping, their page RMG Shipping API Technical User Guide, or similar documentation to learn more about enhancement codes.

Advanced Options

Royal Mail supports certain advanced options, which you can add to the shipment object when creating a shipment or label.

To ensure you always have the most up-to-date information about a carrier's advanced options, use the list carrier options call.

Manifests

Royal Mail requires you to create and print a Sales Order Summary, which you must then hand to the driver who picks up the parcels.

You can generate your Sales Order Summary through the manifest process. When you make your request to the /v1/manifests endpoint, the response will include a link to download the Sales Order Summary PDF.

Please note: You cannot close shipments with dispatch dates in the future, only past or current-date shipments.

Scheduling Pickups

You must set pickups (daily and other schedules) with Royal Mail. This cannot be done via ShipStation API.

Service Points (PUDO)

Royal Mail services do not currently support using service points.

Tracking

ShipStation API's integration with Royal Mail now supports receiving tracking updates. ShipStation API provides tracking notifications, tracking URLs, and tracking events via the API.

Review our ​Track a Package guides​​ for details on tracking with the ShipStation API.

How to Confirm an Active OBA Account

If you are unsure if your Royal Mail account is an OBA account, or if you need your OBA account number, you can follow these steps:

Disconnecting Your Royal Mail Account

See the Disconnect section in our Delete a Carrier page for the process of deleting or disconnecting a carrier from ShipStation API.

Troubleshooting Tips

Here are tips on how to handle some common issues when shipping with Royal Mail.