API Shipping V3 (REST) provides the functionality for customers to take a shipping transaction from creation to collection.
It specifically covers how the Royal Mail API Shipping V3 can be used by business customers to conduct shipping activity with Royal Mail and provides the technical information to build this integration. This specification must be used with the relevant accompanying specifications for customers wishing to interface their systems with Royal Mail services.
Royal Mail API Shipping V3 exposes a fully RESTful service that allows account customers to create shipments, produce labels, and produce documentation for all the tasks required to ship domestic and international items with Royal Mail.
Built on industry standards, Royal Mail API Shipping V3 provides a simple and low cost method for customers to integrate with Royal Mail, and allows them to get shipping quickly. The API offers data streaming to allow customers greater flexibility when generating their labels. There are no costs to customers for using the Royal Mail API Shipping V3 services, however customers??? own development costs must be covered by the customer developing the solution. Royal Mail will not accept any responsibility for these development, implementation and testing costs. Customers should address initial enquiries regarding development of systems for these purposes to their account handler.
This API can be used in conjunction with Royal Mail Pro Shipping, a GUI based shipping platform. For more details on Royal Mail Pro Shipping, including videos on and briefs on updating/ cancelling a shipment and Manifesting please refer to http://www.royalmail.com/pro-shipping-help.
| Attachment | Size |
|---|---|
 Royal Mail API Shipping V3 REST FAQs | 280.3 KB |
 API Shipping V3 Checklist | 20.33 KB |
| Royal Mail Shipping V3 REST API Technical User Guide_v1.1 | 861.84 KB |
| API Shipping V3 Reference Data_v1.8 | 101.63 KB |
Custom API Endpoint
Paths
/shipments
Create Shipment
Use to generate the final delivery label for your packages.
The request is split into several sections:
Shipper - who and where the parcel is coming from - optional if the posting location is to be used.
Destination - who and where the parcel is going to.
Shipment Information - overall package details, individual item details and requested service information.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
The shipment.
application/json
application/json
The shipment(s) are created successfully
Bad Request - one or more shipments are invalid. Details are provided in the error messages.
Unauthorized
Internal Server Error
Service Unavailable
/shipments/{shipmentId}/printDocument
Print Document
Prints the requested document for the shipment.
If item information, description of goods or reason for export have not been provided then the document cannot be printed.
This service can only be used before the shipment has been confirmed either by calling the manifest create request or by closing out via the User Interface.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
Shipment Id
The tracking number or Unique Id of the shipment to print.
{
"maxLength": 21,
"minLength": 13
}Print Document Request
application/json
application/json
The document has printed successfully
Bad Request - the shipment is in an invalid state and the document cannot be printed. Details are provided in the error messages.
Unauthorized
The shipment was not found
Internal Server Error
Service Unavailable
/shipments/{shipmentId}/printLabel
Print Label
Prints the label for the shipment.
Moves the shipment to processed, ready to manifest, if the shipment was not already in a processed state.
This service can only be used before the shipment has been confirmed either by calling the manifest create request or by closing out via the User Interface.
On Hold Shipment
Calling print label on a held shipment will release the shipment from hold and update the shipment date to today.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
Shipment Id
The tracking number or Unique Id of the shipment to print.
{
"maxLength": 21,
"minLength": 13
}Print Label Request
application/json
application/json
The label was printed successfully
Invalid Request. Details are provided in the error messages.
Unauthorized
The shipment was not found
Internal Server Error
Service Unavailable
/shipments/cancel
Cancel Shipments
Can be used to cancel/void one or more current shipping labels.
This service can only be used before the shipment has been confirmed either by calling the manifest create request or by closing out via the User Interface.
There can be a maximum of 99 cancellation requests per call.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
Shipment Cancel Requests
application/json
application/json
All shipments were cancelled successfully
Bad Request - one or more shipments are in an invalid state to cancel. Details are provided in the error messages. No shipments will be cancelled.
Unauthorized
One or more shipments were not found. No shipments will be cancelled.
Internal Server Error
Service Unavailable
/shipments/defer
Defer Shipments
Used to update the shipment shipping date for a current shipment.
A shipment can be deferred by a maximum of 28 days from the date of the request.
This service can only be used before the shipment has been confirmed either by calling the manifest create request or by closing out via the User Interface.
There can be a maximum of 99 defer requests per call.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
The shipments to defer.
application/json
application/json
All shipments were deferred successfully
Bad Request - one or more shipments are in an invalid state to defer or the date is invalid. Details are provided in the error messages. No shipments will be deferred.
Unauthorized
One or more shipments were not found. No shipments will be deferred.
Internal Server Error
Service Unavailable
/shipments/hold
Hold Shipments
Used to put a shipment on hold indefinitely.
A shipment on hold will not be included in any closeouts, but instead will remain in its current state.
Calling printLabel will release the shipment from being held.
This service can only be used before the shipment has been confirmed either by calling the manifest create request or by closing out via the User Interface.
A hold reason must be provided and must match those set in Pro Shipping under your maintenance screens.
If no hold reasons exist, then shipments cannot be put on hold.
There can be a maximum of 99 hold requests per call.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
The shipments to hold.
application/json
application/json
All shipments were put on hold successfully
Bad Request - one or more shipments are in an invalid state to hold or the hold reason is invalid. Details are provided in the error messages. No shipments will be put on hold.
Unauthorized
One or more shipments were not found. No shipments will be put on hold.
Internal Server Error
Service Unavailable
/shipments/release
Release Shipments
Used to release a shipment from being on hold.
This service can only be used for shipments on hold.
Releasing a shipment from hold will update the shipment date to today's date and if the shipment is processed it will be included the next requested manifest.
There can be a maximum of 99 release requests per call.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
Shipments Release Request
application/json
application/json
All shipments were released successfully
Bad Request - one or more shipments are in an invalid state. Details are provided in the error messages. No shipments will be released.
Unauthorized
One or more shipments were not found. No shipments will be released.
Internal Server Error
Service Unavailable
/shipments/serviceAvailability
Service Availability
Retrieve a list of available services for a potential shipment.
Destination - where the parcel is going to.
Shipment Information - overall package details and requested service requirements.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
The shipment.
application/json
application/json
The available service options are returned.
The request was invalid. Details are provided in the error messages.
Unauthorized
Internal Server Error
Service Unavailable
/manifests
Manifest All Shipments
Manifest all shipments that are ready to manifest for a single Posting Location.
Required to confirm parcels are ready to despatch.
Generates the required paperwork to despatch your parcels.
One or more manifests, including the base 64 encoded PDF and manifest number will be returned.
Note: All average weight shipments are ignored and need to be closed out via Shipment Processing
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
Request
application/json
application/json
The manifest(s) have created successfully
Bad Request - the posting location is required or invalid, or there are no shipments to manifest. Details are provided in the error messages.
Unauthorized
Internal Server Error
Service Unavailable
/manifests/bycarrier
Manifest by Carrier Code(s)
Manifest shipments created with the given carrier codes that are ready to manifest for a single Posting Location.
Required to confirm parcels are ready to despatch.
Generates the required paperwork to despatch your parcels.
One or more manifests, including the base 64 encoded PDF and manifest number will be returned.
Note: All average weight shipments are ignored and need to be closed out via Shipment Processing
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
application/json
application/json
The manifest(s) have created successfully
Bad Request - the posting location is required or invalid, there are no shipments to manifest or the carrier codes are invalid. Details are provided in the error messages.
Unauthorized
Internal Server Error
Service Unavailable
/manifests/byservice
Manifest by Service Code(s)
Manifest shipments created with the given service codes that are ready to manifest for a single Posting Location.
Required to confirm parcels are ready to despatch.
Generates the required paperwork to despatch your parcels.
One or more manifests, including the base 64 encoded PDF and manifest number will be returned.
Note: All average weight shipments are ignored and need to be closed out via Shipment Processing
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
application/json
application/json
The manifest(s) have created successfully
Bad Request - the posting location is required or invalid, there are no shipments to manifest or the service codes are invalid. Details are provided in the error messages.
Unauthorized
Internal Server Error
Service Unavailable
/addresses
Get Addresses
Get all of your stored addresses
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
application/json
All existing addresses are returned
Unauthorized
Internal Server Error
Service Unavailable
Create Address
Add a new address to your address book that you can then use in your shipment requests.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
The address.
application/json
application/json
The address was created successfully
Bad Request - the address is invalid. Details are provided in the error messages.
Unauthorized
Internal Server Error
Service Unavailable
/addresses/{addressId}
Get Address
Get the address specified by your unique Address ID.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
Your unique Address ID.
application/json
The address is found and returned successfully
Unauthorized
Address not found
Internal Server Error
Service Unavailable
Update address
Update an address that is already in your address book with new details. The whole address will be replaced with
new details.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
Your unique Address ID of the address to update.
The address with the updated details.
application/json
application/json
The address was updated successfully
Bad Request - the address is invalid. Details are provided in the error messages.
Unauthorized
Address not found
Internal Server Error
Service Unavailable
Delete Address
Deletes the specified address.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
Your unique Address ID of the address to delete.
application/json
The address was deleted successfully
Unable to delete the address
Unauthorized
Address not found
Internal Server Error
Service Unavailable
/token
Authenticates a User and provides token.
Provides security token.
Client ID
Client Secret
User Name
Password in plain text
application/json
Token is created.
Unauthorized
Internal Server Error
Service Unavailable
/items
Get Items
Get all of your stored items
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
application/json
All existing items are returned
Unauthorized
Internal Server Error
Service Unavailable
Create Item
Add a new item to your stored items that you can then use in your shipment requests.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
The item.
application/json
application/json
The item was created successfully
Bad Request - the request is invalid. Details are provided in the error messages.
Unauthorized
Internal Server Error
Service Unavailable
/items/{itemId}
Get Item
Get the item specified by your unique Item ID.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
Your unique Item ID.
application/json
The item is found and returned successfully
Unauthorized
Item not found
Internal Server Error
Service Unavailable
Update item
Update an item that is already stored with new details. The whole item will be replaced with new details.
Client ID
Authorisation token required to invoke this operation. Can be retrieved by invoking the /token operation.
Your unique Item ID of the item to update.
The item with the updated details.
application/json
application/json
The item was updated successfully
Bad Request - the request is invalid. Details are provided in the error messages.
Unauthorized
Item not found
Internal Server Error
Service Unavailable