Upload
others
View
3
Download
0
Embed Size (px)
Citation preview
23th Oct 2018 Page 1 of 60 V2.72
API
Specification
Royal Mail Group
API Shipping V2 (REST)
Technical User Guide
This API specification details the
requirements for integrating with Royal Mail
API Shipping V2 (REST). It specifically
covers how API Shipping V2 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. The API
Shipping function can be used in conjunction
with Pro Shipping, the GUI associated system.
23rd Oct 2018 Page 2 of 60 V2.72
Contents
1 Document Control ......................................... 4
1.1 Terms and Abbreviations ............................................................................................ 4 1.2 Version History ........................................................................................................... 5
2 Overview ................................................. 5 3 Purpose .................................................. 7 4 Introduction to API Shipping V2 .......................... 9
4.1 Overview ..................................................................................................................... 9
4.2 Interface Components ............................................................................................... 11 5 Integrating with API Shipping V2 ........................ 12
5.1 Terms & Conditions .................................................................................................. 13 5.2 API Access ................................................................................................................ 13
5.3 Live Deployment ....................................................................................................... 14 5.4 API Versioning .......................................................................................................... 14
6 Shipping Services ....................................... 15
6.1 Business Services ...................................................................................................... 15 6.2 Standard process/API flow ........................................................................................ 16
Figure 6 – Create Shipment/Manifest With Included Label Flow ....................................... 20 6.3 Offline Barcoding ...................................................................................................... 20
6.4 HTTP Header Information ........................................................................................ 21
6.4.1 Description ......................................................................................................... 21
6.4.2 Request Message ................................................................................................ 21 6.4.3 Example Data ..................................................................................................... 21
6.5 Get Token .................................................................................................................. 22 6.5.1 Request Message ................................................................................................ 22 6.5.2 Response Message ............................................................................................. 22
6.5.3 Example Data ..................................................................................................... 22 6.6 Create Shipment ........................................................................................................ 24
6.6.1 Create Domestic Shipment ................................................................................ 24 6.6.1.1 Request Message ............................................................................................ 24
6.6.1.2 Response Message.......................................................................................... 28 6.6.2 Create International Shipment ........................................................................... 29
6.6.2.1 Request Message ............................................................................................ 29 6.6.2.2 Response Message.......................................................................................... 31 6.6.3 Example Data ..................................................................................................... 31
6.7 Update Shipment ....................................................................................................... 36 6.7.1 Request Message ................................................................................................ 36
6.7.2 Response Message ............................................................................................. 36 6.7.3 Example Data ..................................................................................................... 36
6.8 Cancel Shipment ....................................................................................................... 38 6.8.1 Request Message ................................................................................................ 38 6.8.2 Response Message ............................................................................................. 38
6.8.3 Example Data ..................................................................................................... 38
6.9 Print Label ................................................................................................................. 40
6.9.1 Request Message ................................................................................................ 40 6.9.2 Response Message ............................................................................................. 41
23rd Oct 2018 Page 3 of 60 V2.72
6.9.3 Example Data ..................................................................................................... 42 6.10 Print Documents .................................................................................................... 45
6.10.1 Request Message ................................................................................................ 45 6.10.2 Response Message ............................................................................................. 45 6.10.3 Example Data ..................................................................................................... 45
6.11 Create Manifest ...................................................................................................... 47 6.11.1 Request Message ................................................................................................ 47 6.11.2 Response Message ............................................................................................. 47 6.11.3 Example Data ..................................................................................................... 48
6.12 Print Manifest ........................................................................................................ 49
6.12.1 Request Message ................................................................................................ 49 6.12.2 Response Message ............................................................................................. 50
6.12.3 Example Data ..................................................................................................... 50 7 Error Handling .......................................... 51
7.1 Overview ................................................................................................................... 51 7.2 Technical Errors ........................................................................................................ 52
7.2.1 Example Data ..................................................................................................... 52 7.3 Business Errors .......................................................................................................... 53
7.3.1 Example Data ..................................................................................................... 53 8 Non-Functional Characteristics .......................... 55
8.1 Availability ................................................................................................................ 55 8.1.1 Service Hours ..................................................................................................... 55 8.1.2 Maintenance Windows....................................................................................... 55
8.1.3 Unavailability ..................................................................................................... 55
8.2 Performance .............................................................................................................. 55 8.3 Security...................................................................................................................... 55
9 Frequently Asked Questions .............................. 56 10 Appendix A – Common Data Types .......................... 57
10.1 Address .................................................................................................................. 57 10.2 Contact ................................................................................................................... 57 10.3 Measurement ......................................................................................................... 58
11 Appendix B – Reference Data ............................. 59
11.1 Allowable Character Set ........................................................................................ 59 11.2 Shipment Status Codes .......................................................................................... 60
23rd Oct 2018 Page 4 of 60 V2.72
1 Document Control
1.1 Terms and Abbreviations
Term Meaning
Allocated Shipment with a Service Type / Service / Service
Format and shipment number but not printed
Base64 A standard binary-to-text encoding scheme that is
used to represent binary data in an ASCII string
format. Used to include binary data with an XML
structure
HTTPS Hypertext Transfer Protocol over SSL
IP Internet Protocol
JWT JSON Web Token
Manifested Customer Collection Receipt has been created and
Customer Collection Receipt has been printed
OBA Online Business Account
Printed Shipment with Service Type / Service / Service
Format and shipment number and the label(s) printed
Pro
Shipping
The GUI based shipping platform that can be used in
conjunction with API Shipping to create shipments,
update shipments, Manifest and create reports.
REST Representational State Transfer
SHA-1 Secure Hash Algorithm 1
URL Uniform Resource Locator
Table 1 – Terms and Abbreviations
23rd Oct 2018 Page 5 of 60 V2.72
1.2 Version History
Version Date Notes
2.7.1 31/08/2018 Initial version based on Version 2.7.1 of
API Shipping V2 (SOAP).
2.7.2 23/10/2018 Updates include:
- New POST /shipments operation to create
international and domestic shipments (POST
/domestic operation deprecated).
- New PUT
/shipments/{shipmentNumber}/documents
operation to create international
documents
- Now includes International Services and
also the combined API response
enhancements that can be selected through
the Pro Shipping Maintenance>Label Options
screen.
2.7.3 21/06/2019 In reference to demand RMGBIG-5540-
Updated include the changes in the
mappings for the two fields:
StateOrProvince & County for the following
operations:
-On the request side
Create Shipment/
updateShipment/
domestic/
-On the reponse side
printLabel/
**
Table 2 – Document Version History
2 Overview
Royal Mail API Shipping V2 exposes a web service that allows
account customers to create shipments, produce labels, and
produce documentation for all the tasks required to ship items
with Royal Mail. Built on industry standards, API Shipping V2
provides a simple and low cost method for customers to
23rd Oct 2018 Page 6 of 60 V2.72
integrate with Royal Mail, and allows them to get shipping
quickly.
There are no costs to customers for using the API Shipping V2
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.
23rd Oct 2018 Page 7 of 60 V2.72
3 Purpose
This document is to provide Royal Mail’s customers with
guidelines and detailed specifications for integrating with
the API Shipping V2 REST web service.
The document details:
The specification for the web service interface
Description of errors the API can return
Non-functional characteristics of the API including response times, service availability and security
considerations.
This document is primarily intended to be read by developers
and other technical roles involved with integrating customer
systems’ with API Shipping. This document should be read in
conjunction with the following artefacts which are available
from the API Shipping V2 page on:
https://developer.royalmail.net:
API Shipping V2 Swagger
API Shipping V2 Reference Data
API Shipping V2 FAQ
API Shipping V2 Password Generator
The API Shipping REST operations and HTTP method which are
defined in this document are:
GET /token
POST /domestic
POST /shipments
PUT /shipments/{shipmentNumber}/documents
PUT /{shipmentNumber}
DELETE /{shipmentNumber}
PUT /{shipmentNumber}/label
POST /manifest
PUT /manifest
For details of how to set up API Shipping Passwords, see API
Shipping V2 page on https://developer.royalmail.net. For more
help including videos, on setting up Pro Shipping User
Passwords and their user permissions, Label Printers and
https://developer.royalmail.net/
23rd Oct 2018 Page 8 of 60 V2.72
creating reports visit the Royal Mail Pro Shipping Support
hub: www.royalmail.com/pro-shipping-help. This set up is
needed for both the Onboarding and Production Environments.
23rd Oct 2018 Page 9 of 60 V2.72
4 Introduction to API Shipping V2
4.1 Overview
API Shipping V2 provides the functionality for customers to
take a shipping transaction from creation to collection.
In simplest terms, the logical flow is as follows:
Create Shipment – the details of an item are provided to Royal Mail, and a shipment is created on the system. The
status of the shipment is ‘Allocated’.
Print Label – once a shipment has been created, the label for it can be printed. Once printed, the status of the
shipment is updated to ‘Printed’.
Print Document(s) – once a Non-UK international shipment has been created, international documents can be printed.
The Print Document request will validate you have the
pre-requisite data and return the PDF documents for CN22,
CN23 and/or Commercial Invoice (CI).
Manifest Shipments – before items are collected, the customer must submit details of all the items to Royal
Mail and print off the Customer Collection Receipt for
the driver. The Create Manifest call submits the details
for all shipments that are in the ‘Printed’ state to
Royal Mail (those that are in the ‘Allocated’ state are
ignored). The status of these shipments is then set to
‘Manifested’, and they can no longer be updated or
cancelled.
There are four performance enhancements that can be used, if
enabled in the Pro Shipping GUI under Maintenance> Label
Options:
Base64 /label operation response data included in the /domestic and /shipments operation responses if combined
Create Shipment/Include Print Label enabled
Base64 /label operation response data included in the /domestic and /shipments operations response when
creating a domestic shipment, for a Tracked Returns
shipment if combined Create Shipment/Include Print
Label/Include Returns Label enabled (excludes domestic
shipments to Channel Islands)
Base64 Customs Document labels data included in the /shipments operation response when creating an
international shipment if combined Create
Shipment/Include CN Documentation enabled
Base64 PUT /manifest (print manifest) operation response data included in the POST /manifest (create manifest)
23rd Oct 2018 Page 10 of 60 V2.72
operation response if combined Create Manifest/Include
Manifest Image enabled
Before turning on any of the above enhancements in the Royal
Mail Pro Shipping system it is recommended that you test these
features in your On-boarding environment prior to implementing
in your live API Shipping integration.
Unless you have been granted an exemption, your shipments will
be subject to a clean sweep process. This is a process that
runs at a specific time each night, and automatically
manifests any ‘Printed’ shipments that have not already been
manifested.
Section 6 provides further detailed information especially
about the different process/API flows for the business
services used by you.
23rd Oct 2018 Page 11 of 60 V2.72
4.2 Interface Components
Please see
Figure 1 below for a graphical representation of the interface
between Royal Mail and you for API Shipping V2. This document
covers what information is to be exchanged, how this
information is structured and the means by which it is
transferred.
Figure 1 – API Shipping V2
Customer System
GET /shipping/v2/token
POST /shipping/v2/domestic
POST /shipping/v2/shipments
PUT /shipping/v2/shipments/{shipmentNumber}/documents
PUT /shipping/v2/{shipmentNumber}
DELETE /shipping/v2/{shipmentNumber}
PUT /shipping/v2/{shipmentNumber}/label
POST /shipping/v2/manifest
PUT /shipping/v2/manifest
HTT
PS
Scope of this document
23rd Oct 2018 Page 12 of 60 V2.72
5 Integrating with API Shipping V2
The high-level process associated with integrating with API
Shipping V2 is represented in the diagram below and described
in the sections which follow.
Figure 2 – Process for Integrating with the API
Access to the service is managed through Royal Mail’s API
Management system.
New users of the system will need to:
1. Sign up for an account and accept the terms and conditions on the Royal Mail API (Developer) Portal
(https://developer.royalmail.net).
2. Register the customer side ‘application’ which will be calling the API. When the application is registered, it
will be assigned a unique system-generated Client ID and
Secret which is needed to securely access the API. It is
important that these credentials are noted and securely
stored.
3. Request to subscribe to the API. This will result in an e-mail being automatically generated and sent to the
Royal Mail Customer Solutions team.
4. Once approved, and API login credentials issued to you, testing can be performed against the API in a sandboxed
onboarding environment that allows you to test the
integration.
5. Once all required testing has completed in the onboarding environment, access to the Live production system will be
provided at a mutually agreed date/time.
Existing users who already have an account with Royal Mail’s
API Management system will need to perform step 2 onwards if
the application accessing the API is different to any
currently registered applications. If the application
accessing the API is already registered, existing customers
will need to perform step 3 onwards.
Sign Up
Register Your Application
Select Royal Mail API Shipping V2 (REST)
Subscribe to API
On-boarding / Testing
Live Deployment
https://developer.royalmail.net/
23rd Oct 2018 Page 13 of 60 V2.72
5.1 Terms & Conditions
You must accept the Royal Mail Terms and Conditions on the API
Developer Portal when creating your customer account and note
the Terms & Conditions on https://proshipping.royalmail.com. These cover the ways in which the service may be used and any
integration activities must abide by these.
Of particular note to developers:
The onboarding environment may not be used for performance testing. This is a small scale system for
functional testing only.
Repeated reprints of labels or Customer Collection Receipts will be flagged to Royal Mail and may result in
an investigation.
Cancelled label information is automatically shared with Royal Mail Revenue Protection, and should a cancelled
label be identified on an item in the Royal Mail Network,
you will be charged on your account and an additional
handling fee applied.
Where specified, weights should be accurate. Discrepancies between reported and actual weights will be
investigated by Royal Mail.
All Royal Mail APIs impose a cap on the number of transactions for each customer. Excessive volumes of
traffic within a short period will result in transactions
being rejected.
The Customer Data will be held by us on our servers for a limited period of time to enable users to run activity
reports in Pro Shipping. For a brief and video on reports
available and GUI based End of Day manifesting process
visit the Pro Shipping Support hub:
www.royalmail.com/pro-shipping-help. After 13 months we
will delete such Customer Data.
5.2 API Access
Both onboarding and live access to the API is obtained via the
following URL:
https://api.royalmail.net/shipping/v2
Please note that the Client ID and Secret must be provided in
the HTTP header of all API requests otherwise access to the
API will be rejected and a HTTP 401 (Unauthorised) will be
returned. The Client ID and Secret are obtained by registering
an application on the RMG API Management site.
You must complete all required test activities in the
onboarding environment prior to being permitted access to the
live environment by the Royal Mail Customer Solutions Team.
http://www.royalmail.com/pro-shipping-helphttps://api.royalmail.net/shipping
23rd Oct 2018 Page 14 of 60 V2.72
Once you log in on the developer portal and have been
authorized to use your subscribed APP, the onboarding
environment is made available to you. This will allow you to
test your APP integration without data being passed through to
the Royal Mail operational and billing systems and without
incurring any charges against your account.
You will be provided with a contact in Royal Mail Customer
Solutions who will take you through the onboarding process and
provide you with the required additional security credentials
to access the API. Once you have successfully demonstrated
that your system works with ours, and that you can produce
labels to the required level of quality for all services on
your account and you can successfully manifest your shipments,
you will be granted access to the live system and can begin
shipping items.
Please see section 7 for a full list of technical and business
error codes which are returned from this API.
5.3 Live Deployment
Once you have completed all required testing in the onboarding
environment you will be provided with access to the live
production system.
If new products or services are added to your account, you may
be asked to demonstrate that you have these working correctly
in the onboarding environment before you are allowed to use
them on the live system.
5.4 API Versioning
Royal Mail is continuously working to improve its technology,
and as part of this process updates to the services provided
may on occasion necessitate a new API version. Royal Mail will
look to maintain three versions of the API; as new versions
are introduced, previous versions move down the stack until
they are ultimately removed completely:
Latest version
Previous version
Deprecated version
You will always be encouraged to integrate against the latest
version as this will give you the longest stable period
without the need to change, but if you have already begun
integration activities when a new version is released then you
will be able to integrate against the previous version. You
should not integrate against the deprecated version.
23rd Oct 2018 Page 15 of 60 V2.72
6 Shipping Services
This section describes in detail the services provided by the
Shipping V2 API and the message structure and fields of
request and response messages for each operation.
These operations are also specified in the Swagger which can
be downloaded from the API Shipping V2 REST page on the Royal
Mail API (Developer) Portal by clicking on the 'Open API'
link.
6.1 Business Services
API Shipping V2 is a service offered to RM customers to
request for the creation / update / cancellation of a
shipment, printing of a label, and creation/printing of a
manifest.
The table below provides an overview of the services that are
supported by this API, grouped by functional areas.
Service API Operation Description Technolog
y
Conversatio
n Style
Security
Get
Authorisat
ion Token
GET /token Creates a JWT
security
token to be
used when
invoking
business
operations to
authorise
access.
JSON over
HTTPS
(REST)
Synchronous
Request /
Response
Shipment
Create
Domestic
Shipment
POST /domestic Creates a
domestic
shipment on
the system
Deprecated:
Please use
/shipments
operation
below.
JSON over
HTTPS
(REST)
Synchronous
Request /
Response
Create
Internatio
nal or
Domestic
Shipment
POST /shipments Creates an
international
shipment on
the system
JSON over
HTTPS
(REST)
Synchronous
Request /
Response
https://developer.royalmail.net/https://developer.royalmail.net/
23rd Oct 2018 Page 16 of 60 V2.72
Service API Operation Description Technolog
y
Conversatio
n Style
Create
Internatio
nal
Documents
PUT
/shipments/{shipm
entNumber}/docume
nts
Creates
international
documents for
international
shipments
JSON over
HTTPS
(REST)
Synchronous
Request /
Response
Update
Shipment
PUT
/{shipmentNumber}
Updates the
details of a
shipment that
has been
created but
not
manifested
JSON over
HTTPS
(REST)
Synchronous
Request /
Response
Cancel
Shipment
DELETE
/{shipmentNumber}
Cancels a
shipment that
has been
created but
not
manifested
JSON over
HTTPS
(REST)
Synchronous
Request /
Response
Label
PUT
/{shipmentNumber}
/label
Prints a
label for a
shipment that
has been
created
JSON over
HTTPS
(REST)
Synchronous
Request /
Response
Manifest
Create
Manifest
POST /manifest Manifests
current
shipments
JSON over
HTTPS
(REST)
Synchronous
Request /
Response
Manifest
PUT /manifest Provides a
printable
manifest in
PDF format
JSON over
HTTPS
(REST)
Synchronous
Request /
Response
Table 3 – Business Services
Based on the business service you are using, you have to go
through different process/flows. These process/API flows
related to each business service are explained below.
6.2 Standard process/API flow
This standard process is relevant to you if you use normal API
calls to create shipment, print the label and create manifest
by EOD (End of Day). It should be noted that the API flow
explained in this section doesn’t apply if you use offline
barcoding.
There is also a standard process for retrieving a Royal Mail
authorization token which is required to be sent in all
business operations to allow the action requested.
23rd Oct 2018 Page 17 of 60 V2.72
Below are some of the main flows which come under these
categories:
Get Authorisation Token to be sent in subsequent business operation calls:
Figure 3 – Get Authorisation Token Flow
Business Operation Request
Customer App Royal Mail
GET /token Request ( User name & encoded hashed password )
GET /token Response
( Authorisation token)
Plain text password as supplied by Royal Mail to the user must be sent as an encoded SHA-1 hash.
( Send authorisation token)
( token is valid )
Business Operation Response
This process is repeated if the token expires.
Successfully created token is valid for 4 hours.
23rd Oct 2018 Page 18 of 60 V2.72
Create/Update Shipment Request (Domestic/International) with label in standard PDF
format:
Figure 4 – Create Shipment With Label In PDF Format
Flow
PUT /manifest Response
( token, serviceOfferingCode (optional), yourDescription, yourReference )
POST /manifest Response
( manifestBatchNumber )
PUT /{shipmentNumber}/label Request
Customer App Royal Mail
POST /shipments Request,PUT /{shipmentNumber } Request
POST /manifest Request
PUT /manifest Request
( token, offlineShipment fields omitted in request )
POST /shipments Response,PUT /{shipmentNumber} Response pdate Shipment Response ( itemID (2D) for each shipment and shipmentNumber (1D) )
Any shipment number returned as 14 characters is only a reference between API calls and cannot be used for tracking shipments.
( token, shipmentNumber, outputFormat = PDF )
( label in base 64 encoded PDF format ) PUT /{shipmentNumber}/label Response
Adding a Service Offering code to the Create Manifest request will only manifest shipments for that service code
End of Day (EOD)
( Sales Order Summary / manifest in base 64 encoded PDF format )
( token, manifestBatchNumber )
This process is repeated throughout the day to produce a shipping label
GET /token Request
( User name & encoded hashed password )
GET /token Response ( Authorisation token valid for 4 hours)
PUT /shipments/{shipmentNumber}/documents Request
( token, shipmentNumber, documentName = CN22 / CN23 / CI )
PUT /shipments/{shipmentNumber}/documents Response ( Customs documentation in base 64 encoded PDF format )
Optional for International Shipments to non UK destinations to generate Customs declarations
23rd Oct 2018 Page 19 of 60 V2.72
Create/Update Shipment Request (Domestic/International) with Datastream:
Figure 5 – Create Shipment With Datastream Flow
Each of the operations mentioned in the flow diagrams above
i.e. POST /domestic request, PUT /{shipmentNumber}/label
request etc. are detailed further in sections below in this
document.
NOTE: You should call the PUT /{shipmentNumber}/label request
and PUT /shipments/{shipmentNumber}/documents (required only
for optional Customs Documentation for international non-UK
shipments) operations for each shipment separately.
PUT /manifest Response
( token, serviceOfferingCode (optional), yourDescription, yourReference )
POST /manifest Response ( manifestBatchNumber )
PUT /{shipmentNumber}/label Request
Customer App
Royal Mail
POST /shipments Request,PUT /{shipmentNumber} Request
POST /manifest Request
PUT /manifest Request
( token, offlineShipment elements omitted in request )
POST /shipments Request,PUT /{shipmentNumber} Response
( itemID (2D) for each shipment and shipmentNumber (1D) )
Any shipment number returned as 14 characters is only a reference between API calls and cannot be used for tracking shipments.
( token, shipmentNumber, outputFormat = DSPDF / PNG / DSPNG )
( depends on output Format selected in print Label) PUT /{shipmentNumber}/label Response
Adding a Service Offering code to the Create Manifest request will only manifest shipments for that service code
End of Day (EOD)
( Sales Order Summary / manifest in base 64 encoded PDF format )
( token, manifestBatchNumber )
This process is repeated throughout the day to produce a shipping label
Output format of PNG or DSPNG requires the customer to generate the label template to Royal Mail requirements from their own system.
GET /token Request ( User name & encoded hashed password )
GET /token Response ( Authorisation token valid for 4 hours)
PUT /shipments/{shipmentNumber}/documents Request ( token, shipmentNumber, documentName = CN22 / CN23 / CI )
PUT /shipments/{shipmentNumber}/documents Response ( Customs documentation in base 64 encoded PDF format )
Optional for International Shipments to non UK destinations to generate Customs declarations
23rd Oct 2018 Page 20 of 60 V2.72
Print Label response included in Create Shipment and Print Manifest response
included in Create Manifest:
Figure 6 – Create Shipment/Manifest With Included Label
Flow
6.3 Offline Barcoding
Offline barcoding requires 1D barcode ranges in order to
produce and print your own labels using these ranges. API
Shipping V2 REST does not support the retrieval of 1D barcode
ranges. Contact the Royal Mail Customer Solutions team for
further guidance.
( token, serviceOfferingCode (optional), yourDescription, yourReference )
POST /manifest Response ( manifestBatchNumber including manifest in base 64 encoded
PDF format)
Customer App
Royal Mail
POST /shipments Request
POST /manifest Request
( token, offlineShipment elements omitted in request )
POST /shipments Response ( itemID (2D) for each shipment and shipmentNumber (1D) including
base 64 encoded PDF label)
Any shipment number returned as 14 characters is only a reference between API calls and cannot be used for tracking shipments.
Adding a Service Offering code to the Create Manifest request will only manifest shipments for that service code
End of Day (EOD)
This process is repeated throughout the day to produce a shipping label
GET /token Request ( User name & encoded hashed password )
GET /token Response ( Authorisation token valid for 4 hours)
PUT /shipments/{shipmentNumber}/documents Request ( token, shipmentNumber, documentName = CN22 / CN23 / CI )
PUT /shipments/{shipmentNumber}/documents Response ( Customs documentation in base 64 encoded PDF format )
Optional for International Shipments to non UK destinations to generate Customs declarations
Only weight, recipient address and shipping date can be updated
PUT /{shipmentNumber} Request ( token, shipmentNumber, elements to update )
PUT /{shipmentNumber} Response ( shipmentNumber and updated elements)
23rd Oct 2018 Page 21 of 60 V2.72
6.4 HTTP Header Information
6.4.1 Description
The purpose of the HTTP header is to support security and
logging functionally within the Royal Mail systems and it is
mandatory that it is provided in the request message.
6.4.2 Request Message
All service requests to this API will be authorised in
accordance with the Client ID, Secret and Authorisation Token
passed in the HTTP headers. Please see table below for the
elements which need to be populated in the HTTP header.
Parameter Optional Description
X-IBM-Client-Id No Similar to a client username. Required
to access the API.
X-IBM-Client-
Secret
No Similar to a client password. Required
to access the API.
X-RMG-Auth-Token No A JSON Web Token (JWT) required to
permit the user to invoke the business
services exposed by the API. The JWT is
valid for 4 hours.
Table 4 – HTTP Header Information in the API Request
The Client ID and Client-Secret are provided to you when you
register your Application on the Developer Portal. See section
5 for more details.
The authorisation token can be retrieved by calling the /token
operation passing in your user credentials as supplied by
Royal Mail. See section 6.5 for more details. Once a valid
token is acquired, the token must be sent in the HTTP header
when invoking any subsequent business operations.
6.4.3 Example Data
Example request data for the HTTP Header:
Parameter Value
X-IBM-Client-Id f0e4f151-2041-4df2-b31d
X-IBM-Client-Secret kT0lB2dK0wF6mK0rD8sD7oE7vP2mG7l
X-RMG-Auth-Token eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjU4NzQ3MjQsI
mlhdCI6MTUyNTg2MDMyNCwidXNlcklkIjoiSE9VTlNMT1c
xIiwicGFzc3dvcmQiOiJyWWJHbUZqb3kzNU85M2xia01za
zFwbmVpSVE9In0.D662-
SDHQxP1ZqUOc9JHmOIW96ICV0Z-Co8eYRZiSwU
Table 5 – Example HTTP Header Information for API Request
23rd Oct 2018 Page 22 of 60 V2.72
6.5 Get Token
Get an authorisation security token by passing in the user's
security credentials. This token must be sent in all
subsequent calls to the API in order to be allowed access.
6.5.1 Request Message
URL Path: https://api.royalmail.net/shipping/v2/token
The credentials to be sent in the HTTP header comprise the
following:
The username of the API user account,
The encoded SHA-1 hash of the password of the API user
account.
Parameter Max
Lengt
h
Occur
s
Data
Type
Description
X-RMG-User-Name N/A 1-1 String Mandatory. API username as
supplied by Royal Mail.
X-RMG-Password N/A 1-1 String Mandatory. Encoded SHA-1 hash of
the plain text password. The plain
text password will be provided to
the user by Royal Mail and it is
the user's responsibility to send
the encoded SHA-1 hash of the
password.
Royal Mail has provided a Password
Generator utility on the Developer
Portal to enable users to perform
a SHA-1 hashing and encoding of
the password.
Table 6 – Get Token Request Message
6.5.2 Response Message
The body of the response message contains the token populated
in the field as shown below. A successful response will be
returned as a standard HTTP response code of 200 (Ok).
Field Max
Lengt
h
Occur
s
Data
Type
Description
token N/A 1-1 String Authorisation token.
The authorisation token in the form of a JWT is valid for 4
hours. Once expired (401 unauthorized error response
returned), a new token needs to be requested.
6.5.3 Example Data
Get Token Request
GET https://api.royalmail.net/shipping/v2/token HTTP/1.1
23rd Oct 2018 Page 23 of 60 V2.72
X-IBM-Client-Id: a77f6e62-d4c5-4421-9af7-ba8fd3ed6eff
X-IBM-Client-Secret: C8rG0uG5gI3hK3tR3iW6lR0sY0kE1pG8wU3nQ4mA0xP0kB6aU7
X-RMG-User-Name: HOUNSLOW1
X-RMG-Password: rYbGmFjoy35O93lbkMsk1pneiIQ=
Get Token Response
HTTP/1.1 200 OK
Content-Type: application/json
"token":
"eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjU4NzQ3MjQsImlhdCI6MTUyNTg2MDMyNCwidXNlcklkIjoiS
E9VTlNMT1cxIiwicGFzc3dvcmQiOiJyWWJHbUZqb3kzNU85M2xia01zazFwbmVpSVE9In0.D662-
SDHQxP1ZqUOc9JHmOIW96ICV0Z-Co8eYRZiSwU"
23rd Oct 2018 Page 24 of 60 V2.72
6.6 Create Shipment
The Create Shipment operations either results in a domestic or
international shipment being created (based on the information
provided in the request) on Royal Mail's platform or an
appropriate error message and HTTP status code being returned
to the customer.
The sub-sections below describes the two operations used to
create these two types of shipments.
To invoke the operation, the customer shipping system
constructs a JSON request message as described below.
6.6.1 Create Domestic Shipment
Create a domestic shipment whose recipient's address must be a
UK country code. E.g. 'GB', 'JE' etc.
6.6.1.1 Request Message
URL Path: Two URLs can be used to create a domestic shipment.
The /domestic URL is deprecated and /shipments should be used
instead.
https://api.royalmail.net/shipping/v2/shipments
https://api.royalmail.net/shipping/v2/domestic (deprecated)
Fields in the request message are shown in the table below.
Field Max
Lengt
h
Occur
s
Data
Type
Description
shipmentType 8 1-1 String Mandatory. Specifies whether the
shipment being created is a
standard delivery service or a
returns service. Accepted values
are ‘Delivery’ and ‘Return’.
Please note that this field is not
case sensitive.
service N/A 1-1 Object Mandatory. Object containing
service fields
service.format 4 0-1 String The Service Format code for the
shipment. Note that this field is
case sensitive. For the list of
permissible values, please go to
API Shipping V2 page on the Royal
Mail API (Developer) Portal and
refer to API Shipping Reference
Data..
service.occurrence 2 0-1
String Part of the customer’s contract
identifier. In conjunction with
the Service Offering it identifies
an agreement line on the
customer’s account. If only one
Service Reference exists then this
is not required. No leading zero
is required.
https://developer.royalmail.net/https://developer.royalmail.net/
23rd Oct 2018 Page 25 of 60 V2.72
Field Max
Lengt
h
Occur
s
Data
Type
Description
service.offering 3 1-1 String Mandatory. The Service Offering
code for the mail item ordered.
Please note that this field is
case sensitive. For the list of
permissible values, please go to
API Shipping V2 page on the Royal
Mail API (Developer) Portal and
refer to API Shipping Reference
Data..
service.type 4 1-1 String Mandatory. The system Service Type
of the shipment. For the list of
permissible values, please go to
API Shipping V2 page on the Royal
Mail API (Developer) Portal and
refer to API Shipping Reference
Data.
service.signature 1 0-1 Boolean For RM Tracked items only, this
element specifies whether a
signature is required on delivery.
If this element is not included
then it defaults to false.
service.enhancements N/A 0-1 Array List of service enhancement types.
service.enhancements[
]
2 1-* String Enhancement type code.
There can never be more than one
enhancement type specified from
each Service Enhancement Group.
Note that this field is case
sensitive. For the list of
permissible values, please go to
API Shipping V2 page on the Royal
Mail API (Developer) Portal and
refer to API Shipping Reference
Data.
bfpoCode 4 0-1 String For HM Forces (BFPO) Service Type
only when the Service Format is
not International Flat,
International Letter or
International Packet.
For the list of permissible
values, please go to API Shipping
V2 page on the Royal Mail API
(Developer) Portal and refer to
API Shipping Reference Data.
shippingDate 10 0-1 String This is the date that the item
will be physically sent (in the
format YYYY-MM-DD). This may be up
to 28 days in the future. Please
note that for returns a Shipping
date must be provided.
items N/A 0-99 Array List of items to be shipped
items[].offlineShipme
nt
N/A 0-1 Array Not Currently Available.
List of offline items to be
shipped.
Only when you are using the
offline barcoding. These fields
should only be populated once you
have requested and received 1D
barcode ranges from Royal Mail.
https://developer.royalmail.net/https://developer.royalmail.net/https://developer.royalmail.net/https://developer.royalmail.net/https://developer.royalmail.net/https://developer.royalmail.net/https://developer.royalmail.net/https://developer.royalmail.net/
23rd Oct 2018 Page 26 of 60 V2.72
Field Max
Lengt
h
Occur
s
Data
Type
Description
items[].offlineShipme
nt[].number
13 0-1 String Not Currently Available.
Offline 1D Linear Barcode number
assigned to the shipment. This
should be from the 1D barcode
range received by you from Royal
Mail.
items[].offlineShipme
nt[].itemID
8 0-1 String Not Currently Available.
Offline 2D Item ID number assigned
to the shipment. This value is the
same as the Channel Specific
Segment – Unique Identifier value
contained in the 2D barcode.
Details of this value are provided
in the additional information
provided by Customer Solutions.
items[].offlineShipme
nt[].status
35 1-1 String Not Currently Available.
Code for status of Offline
Shipment. Valid values are:
‘AllocatedOffline’: You have to
call the Print Label operation
before adding the shipment to
manifest.
it
‘PrintedOffline’: Print Label is
not required when using this
status in the Create Shipment call
items[].count 2 0-1 Integer Number of items for the associated
weight
items[].weight N/A 1-1 Measure
ment
Mandatory. Item weight details.
See Common Data Type Section 10.3
for further details.
Unit of measure must be ‘g’ for
grams
Weight in grams of each item (no
decimal places). If the service
has a weight band, for example
Special Delivery, then the upper
band will be used.
For example, 150 grams will use
the 100 to 200 grams band. Tracked
services, for example, do not have
a band and therefore take the
actual weight. Note: Where Average
Weight End of Day option is turned
ON, for Average Weight Products
populate with ‘0’. For more
information go to API Shipping V2
page on the Royal Mail API
(Developer) Portal and refer to
API Shipping Reference Data for
Average Weight Products
23rd Oct 2018 Page 27 of 60 V2.72
Field Max
Lengt
h
Occur
s
Data
Type
Description
recipientContact N/A 1-1 Object Mandatory. Object for contact
details. See Common Data Type
Section 10.2 for further details.
Note: If you specify more than 35
characters in name or
complimentary name fields and
generate a PDF label, these fields
will be truncated to 35 characters
in order to fit onto the label. It
is therefore recommended that
customers enter values within the
35 character display limit.
recipientAddress N/A 1-1 Object Mandatory. Object for address
details.
See Common Data Type Section 10.1
for further details.
Note: If you specify more than 35
characters in addressLine1,
addressLine2, addressLine3 or
postTown fields and generate a PDF
label, these fields will be
truncated to 35 characters in
order to fit onto the label. It is
therefore recommended that
customers enter values within the
35 character limit.
senderReference 20 0-1 String This field allows the user to
supply their own reference number.
Where supported (e.g. Tracked
Returns) this number will appear
on the label.
departmentReference 10 0-1 String This is the department reference
code that customers can define in
OBA. This is visible in the system
departmental references GUI.
customerReference 12 0-1 String This field allows customers to
supply a reference that applies to
multiple shipments and is included
to mirror the functionality
offered by the Customer Reference
field in OBA, whereby a reference
can be associated to a group of
items. For references that apply
to a single shipment, the
senderReference field should be
used. Warning: Misuse of this
field may result in incorrect
billing.
23rd Oct 2018 Page 28 of 60 V2.72
Field Max
Lengt
h
Occur
s
Data
Type
Description
safePlace 30
(24)
0-1 String For Tracked non-signature service
offerings only; this field allows
a string that gives details of the
recipient’s designated safeplace
(e.g. “inside the porch”).
If specifying more than 24
characters and generating a PDF
label, this field will be
truncated to 24 characters in
order to fit onto the label. It is
therefore recommended that
customers enter values within the
24 character display limit.
internationalInfo - 0-1 Object Mandatory when creating
international shipment.
See Section 6.6.2 Create
International Shipment for further
details.
Table 7 – Create & Update Shipment Request Message
6.6.1.2 Response Message
A successful response will be returned as a HTTP status code
of 201 (Ok).
The response for a created shipment (domestic and
international) is returned in the response body as a JSON
payload. The table below describes response fields for a
successfully created shipment.
Field Max
Lengt
h
Occur
s
Data
Type
Description
completedShipments N/A 1- ∞ Array List of completed shipments with barcodes and weight.
completedShipments[].shipmen
tItems
N/A 1-99 Array List of completed shipment
details.
completedShipments[].shipmen
tItems[].shipmentNumber
13 1-1 Strin
g
For barcoded products i.e.
you have used offline
barcoding operation, this
field will contain the 1D
barcode number sent in the
request. For non-barcoded
products, this field will
contain the API Shipping V2
internal reference number.
For requests where there are
multiple items, there will
be a corresponding
shipmentNumber for each
item.
completedShipments[].shipmen
tItems[].itemID
N/A 1-1 Strin
g
This is the 2D item ID used
in the label
completedShipments
[].shipmentItems[].status
N/A 1-1 Strin
g
Current status of the item
i.e. Allocated
23rd Oct 2018 Page 29 of 60 V2.72
Field Max
Lengt
h
Occur
s
Data
Type
Description
completedShipments[].shipmen
tItems[].validFrom
N/A 0-1 Date Date time value associated
with when the shipment
status code is valid from.
In 'YYYY-MM-DDThh:mm:ss'
format.
completedShipments[].shipmen
tItems[].label
N/A 0-1 Strin
g
Label in Base64 encoded, PDF
format. Depending on the
scenarios described below,
the label contents returned
can vary depending on the
enabled combinations in the
Pro Shipping GUI.
For both domestic &
international shipments:
1. A standard outward
shipment label is returned
if combined Create Shipment/
Include Label Image are
enabled.
For domestic shipment
(excluding Channel Islands)
only:
2. If #1. above is enabled
and Include Returns Label is
also enabled, then two
shipments will be created
and a standard outward
shipment label is created
for the outward shipment and
a returns label is created
for the return shipment.
For international shipment
only:
3. If #1. above is enabled
and Include CN Documentation
is also enabled, then the
label also includes the CN23
Customs document as well as
the standard outward
shipment label. Note, no
Commercial Invoice is
returned.
Table 8 – Create Shipment Response Message
6.6.2 Create International Shipment
Create an international shipment whose recipient's address is
a non-UK country code.
6.6.2.1 Request Message
URL Path: https://api.royalmail.net/shipping/v2/shipments
The fields in the request message when creating a domestic
shipment as per Section 6.6.1.1 needs to be populated.
23rd Oct 2018 Page 30 of 60 V2.72
International shipment specific fields under the
internationalInfo object must be submitted are shown in the
table below.
Field Max
Lengt
h
Occur
s
Data
Type
Description
parcels N/A 1-1 Array List of parcels in the
shipment. Up to a maximum of
9 parcels.
parcels[].weight N/A 0-1 Measu
remen
t
Weight of shipment. See
Common Data Type Section
10.3 for further details.
parcels[].length N/A 0-1 Measu
remen
t
Length dimension of
shipment, Must in 'cm'. See
Common Data Type Section
10.3 for further details.
parcels[].height N/A 0-1 Measu
remen
t
Height dimension of
shipment, , Must in 'cm'.
See Common Data Type Section
10.3 for further details.
parcels[].width N/A 0-1 Measu
remen
t
Width dimension of shipment,
Must in 'cm'. See Common
Data Type Section 10.3 for
further details.
parcels[].purposeOfShipment 3 0-1 Strin
g
Purpose of shipment (also
known as Nature of Goods).
These are 2-3 character
codes as defined below:
"21" for Returned Goods
“31” for Gift
“32” for Commercial Sample
"91" for Documents
“991” for Mixed Content
"999" for Other
parcels[].explanation N/A 0-1 Strin
g
Comments regarding the
parcel,
parcels[].invoiceNumber N/A 0-1 Strin
g
Invoice number.
parcels[].exportLicenseNumbe
r
N/A 0-1 Strin
g
Export licence number.
parcels[].certificateNumber N/A 0-1 Strin
g
Certificate number.
parcels[].contentDetails N/A 1-1 Array Parcel content details list.
parcels[].contentDetails[].c
ountryOfManufactureCode
2 1-1 Strin
g
Mandatory. 2-digit country
ISO code representing the
country in which the goods
where manufactured. Note
that this field is case
sensitive. For the list of
allowable values, please go
to API Shipping V2 page on
the Royal Mail API
(Developer) Portal and refer
to API Shipping Reference
Data.
parcels[].contentDetails[].m
anufacturersName
N/A 0-1 Strin
g
Name of manufacturer of
goods in the shipment.
parcels[].contentDetails[].d
escription
N/A 0-1 Strin
g
Description of goods being
delivered.
parcels[].contentDetails[].u
nitWeight
N/A 0-1 Measu
remen
t
Weight of content item in
shipment.
23rd Oct 2018 Page 31 of 60 V2.72
Field Max
Lengt
h
Occur
s
Data
Type
Description
parcels[].contentDetails[].u
nitQuantity
N/A 1-1 Numbe
r
Mandatory. Quantity of
content items within the
shipment.
parcels[].contentDetails[].u
nitValue
N/A 1-1 Numbe
r
Mandatory. Value of content
items within the shipment.
parcels[].contentDetails[].c
urrencyCode
3 1-1 Strin
g
Mandatory. 3-digit ISO
currency code for value of
content item within the
shipment.
parcels[].contentDetails[].t
ariffCode
N/A 0-1 Numbe
r
Tariff code for content item
within the shipment.
See https://www.gov.uk/trade-
tariff.
parcels[].contentDetails[].t
ariffDescription
N/A 0-1 Strin
g
Description that compliments
the tariff code supplied.
parcels[].fees N/A 0-1 Numbe
r
Parcel fees.
shipperExporterVatNo N/A 0-1 Strin
g
Exporter’s VAT number
defined in OBA.
recipientImportersVatNo N/A 0-1 Strin
g
Recipient / Importer’s VAT
number.
originalExportShipmentNo N/A 0-1 Strin
g
Original export shipment
number.
documentsOnly N/A 0-1 Boole
an
Indication of export of
documents only.
shipmentDescription N/A 0-1 Strin
g
Description of the shipment.
comments N/A 0-1 Strin
g
Comments regarding the
shipment.
invoiceDate N/A 0-1 Strin
g
Commercial Invoice Date in
the format YYYY-MM-DD.
termsOfDelivery 3 0-1 Strin
g
3 Character code indicating
terms of delivery
(IncoTerms). The relevant
international standard code
for the terms of delivery;
refer to the International
Chamber of Commerce (ICC)
for required listing of
codes.
purchaseOrderRef N/A 0-1 Strin
g
Vendor’s Purchase Order
Number for the shipment.
Table 9 – Create International Shipment Request Message
6.6.2.2 Response Message
A successful response will be returned as a HTTP status code
of 201 (Ok).
The same response fields as per Section 6.6.2.2 when creating
a domestic shipment are returned.
6.6.3 Example Data
The following examples shows the HTTP request and successful
response messages for creating domestic and international
https://www.gov.uk/trade-tariffhttps://www.gov.uk/trade-tariff
23rd Oct 2018 Page 32 of 60 V2.72
shipments. It also shows an example response when 'Create
Shipment/Include Print Label' is enabled in the GUI.
Create Domestic Shipment Request
'Create Shipment/Include Print Label' is not enabled in the
GUI. No label is returned in the response.
Note that if the recipientAddress.countryCode field is
omitted, the default is to create a domestic shipment.
POST https://api.royalmail.net/shipping/v2/domestic HTTP/1.1
X-IBM-Client-Id: a77f6e62-d4c5-4421-9af7-ba8fd3ed6eff
X-IBM-Client-Secret: C8rG0uG5gI3hK3tR3iW6lR0sY0kE1pG8wU3nQ4mA0xP0kB6aU7
X-RMG-Auth-Token:
eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjU4NzQ3MjQsImlhdCI6MTUyNTg2MDMyNCwidXNlcklkIjoiSE
9VTlNMT1cxIiwicGFzc3dvcmQiOiJyWWJHbUZqb3kzNU85M2xia01zazFwbmVpSVE9In0.D662-
SDHQxP1ZqUOc9JHmOIW96ICV0Z-Co8eYRZiSwU
{
"shipmentType": "Delivery",
"service": {
"format": "P",
"occurrence": "1",
"offering": "CRL",
"type": "1",
"signature": "false"
},
"shippingDate": "2015-08-28",
"items": [
{
"count": 1,
"weight": {
"unitOfMeasure": "g",
"value": 250
}
}
],
"recipientContact": {
"name": "Joe Bloggs",
"complementaryName": "Lady Joe",
"telephoneNumber": "07801323456",
"email": "[email protected]"
},
"recipientAddress": {
"buildingName": "One Broadgate",
"buildingNumber": "1",
"addressLine1": "AddressLine 1",
"addressLine2": "AddressLine 2",
"addressLine3": "AddressLine 3",
"stateOrProvince": "NewYork",
"postTown": "London",
"county": "London",
"postCode": "EC2M 2QS"
},
"senderReference": "SendersRef",
"safePlace": "Porch"
}
23rd Oct 2018 Page 33 of 60 V2.72
Create Domestic Shipment Response
HTTP/1.1 201 OK
Content-Type: application/json
{
"completedShipments": [
{
"shipmentItems": [
{
"shipmentNumber": "HY188980152GB
23rd Oct 2018 Page 34 of 60 V2.72
}
],
"recipientContact": {
"name": "Joe Bloggs",
"complementaryName": "Acme Ltd",
"telephoneNumber": "07801323456",
"email": "[email protected]"
},
"recipientAddress": {
"buildingName": "Amphitheatre",
"buildingNumber": 600,
"addressLine1": "Parkway Mountain View",
"addressLine2": "AddressLine 2",
"addressLine3": "AddressLine 3",
"stateOrProvince": "NewYork",
"postTown": "Mountain View",
"county": "CA",
"postCode": "94043",
"countryCode": "US"
},
"senderReference": "DS324354545",
"departmentReference": "DEPTREF",
"customerReference": "CUSTOMERREF",
"safePlace": "Porch",
"internationalInfo": {
"parcels": [
{
"weight": {
"unitOfMeasure": "g",
"value": 25
},
"length": {
"unitOfMeasure": "cm",
"value": 55
},
"height": {
"unitOfMeasure": "cm",
"value": 20
},
"width": {
"unitOfMeasure": "cm",
"value": 30
},
"purposeOfShipment": "31",
"explanation": "Toys",
"invoiceNumber": "12787578435",
"exportLicenseNumber": "6465464565",
"certificateNumber": "123243423",
"contentDetails": [
{
"countryOfManufactureCode": "US",
"manufacturersName": "Bloggs Corp",
"description": "Toys",
"unitWeight": {
"unitOfMeasure": "g",
"value": 25
},
"unitQuantity": 1,
"unitValue": 20.5,
"currencyCode": "USD",
"tariffCode": "9503004100",
"tariffDescription": "Stuffed toys."
}
],
"fees": 20.12
}
],
"shipperExporterVatNo": "GB999999973",
23rd Oct 2018 Page 35 of 60 V2.72
"recipientImportersVatNo": "GB888999964",
"originalExportShipmentNo": "4235454454",
"documentsOnly": false,
"shipmentDescription": "Personal items",
"comments": "Personal items",
"invoiceDate": "2018-08-28",
"termsOfDelivery": "DAP",
"purchaseOrderRef": "910487552"
}
}
Create International Shipment Response
label field value truncated in this example to aid
readability.
HTTP/1.1 201 OK
Content-Type: application/json
{
"completedShipments": [
{
"shipmentItems": [
{
"shipmentNumber": "HY188980152GB",
"itemID": "1000076",
"status": "Printed",
"validFrom": "2015-02-09T09:52:06.000+02:00",
"label":
"JVBERi0xLjQKJdP0zOEKMSAwIG9iago8PAovQ3JlYXRpb25EYXRlKEQ6MjAxODA5M……..="
}
],
"weight": {
"unitOfMeasure": "g",
"value": 25
}
}
]
}
23rd Oct 2018 Page 36 of 60 V2.72
6.7 Update Shipment
The Update Shipment operation allows customers to update the
details of a previously created (but not manifested) shipment,
provided that doing so does not violate the validation rules
applied, or change the barcode number (e.g. it is not possible
to update a Special Delivery item to become a Tracked Next Day
item).
Only one shipment (identified by a single shipment number in
the URL) can be updated per request, although multiple fields
can be updated each time. If any field fails validation, then
an error code will be returned and no fields will be updated.
There is no limit to the number of times a shipment can be
updated.
The status of the shipment is only affected if the recipient
address is updated. The state remains the same if any other
fields are updated (e.g. a shipment with status ‘Allocated’
before an update will be ‘Allocated’ afterwards; a shipment
with status ‘Printed’ will be ‘Printed’ afterwards).
NOTE: The barcode which was allocated during the earlier
create shipment operation cannot be changed through the update
shipment operation and therefore the service.type and
service.enhancements fields cannot be altered. If changes to
these fields are included, an error will be returned.
6.7.1 Request Message
URL Path:
https://api.royalmail.net/shipping/v2/{shipmentNumber}
An Update Shipment request message has the same message
structure as a Create Shipment request. Please see the create
shipment request message in Section 6.6.1.1.
6.7.2 Response Message
A successful response will be returned as a HTTP status code
of 200 (Ok) with the message body confirming the shipment
number updated as per the field below.
Field Max
Lengt
h
Occur
s
Data
Type
Description
shipmentNumber 13 1-1 String The shipment number that has been
updated.
Table 10 – Update Shipment Response Message
6.7.3 Example Data
The following example shows the HTTP request and successful
response messages to update a shipment.
Update Shipment Request
23rd Oct 2018 Page 37 of 60 V2.72
PUT https://api.royalmail.net/shipping/v2/RQ221150289GB HTTP/1.1
X-IBM-Client-Id: a77f6e62-d4c5-4421-9af7-ba8fd3ed6eff
X-IBM-Client-Secret: C8rG0uG5gI3hK3tR3iW6lR0sY0kE1pG8wU3nQ4mA0xP0kB6aU7
X-RMG-Auth-Token:
eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjU4NzQ3MjQsImlhdCI6MTUyNTg2MDMyNCwidXNlcklkIjoiSE
9VTlNMT1cxIiwicGFzc3dvcmQiOiJyWWJHbUZqb3kzNU85M2xia01zazFwbmVpSVE9In0.D662-
SDHQxP1ZqUOc9JHmOIW96ICV0Z-Co8eYRZiSwU
{
"recipientAddress": {
"buildingName": "Beech House",
"buildingNumber": "25",
"addressLine1": "Updated AddressLine 1",
"addressLine2": "Updated AddressLine 2",
"stateOrProvince": "NewYork",
"postTown": "Brighton",
"county": "NY",
"postCode": "BN3 3JA"
}
}
Update Shipment Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"shipmentNumber": "RQ221150275GB"
}
23rd Oct 2018 Page 38 of 60 V2.72
6.8 Cancel Shipment
The Cancel Shipment operation allows customers to cancel a
previously created (but not manifested) shipment. Once a
shipment has been cancelled its status will change from
‘Allocated’ or ‘Printed’ to ‘Cancelled’.
Shipments created by the API can be cancelled by the API call
or the Pro Shipping GUI, and cancelled shipments are visible
in the system. Any Tracked Returns shipments must be cancelled
before midnight as this is when they will be automatically
processed and archived by the system. Only one shipment can be
cancelled in a single request.
Any shipments that can’t be cancelled will be communicated as
an error message as described in section 7.
6.8.1 Request Message
URL Path:
https://api.royalmail.net/shipping/v2/{shipmentNumber}
The shipment number to be cancelled is passed as a parameter
in the URL.
Parameter Max Lengt
h
Occur
s
Data
Type
Description
shipmentNumber 13 1- 1 String The shipment number to be cancelled. The shipment number should be same as
that was received/returned in the
Create Shipment response.
Table 11 – Cancel Shipment Request Message
6.8.2 Response Message
A successful response will be returned as a HTTP status code
of 200 (Ok) with the message body containing the cancelled
shipment number as per the field below.
Field Max
Lengt
h
Occur
s
Data
Type
Description
shipmentNumber 13 1-1 String The shipment number that has been
updated.
Table 12 – Cancel Shipment Response Message
6.8.3 Example Data
Cancel Shipment Request
DELETE https://api.royalmail.net/shipping/v2/RQ221150275GB HTTP/1.1
X-IBM-Client-Id: a77f6e62-d4c5-4421-9af7-ba8fd3ed6eff
X-IBM-Client-Secret: C8rG0uG5gI3hK3tR3iW6lR0sY0kE1pG8wU3nQ4mA0xP0kB6aU7
X-RMG-Auth-Token:
eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjU4NzQ3MjQsImlhdCI6MTUyNTg2MDMyNCwidXNlcklkIjoiSE
23rd Oct 2018 Page 39 of 60 V2.72
9VTlNMT1cxIiwicGFzc3dvcmQiOiJyWWJHbUZqb3kzNU85M2xia01zazFwbmVpSVE9In0.D662-
SDHQxP1ZqUOc9JHmOIW96ICV0Z-Co8eYRZiSwU
Cancel Shipment Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"shipmentNumber": "RQ221150275GB"
}
23rd Oct 2018 Page 40 of 60 V2.72
6.9 Print Label
The print label operation has several functions.
It allows customers to request a label in Base64 encoded PDF format for a specific shipment.
It returns shipment data in JSON format for production of custom labels.
Once the print label operation has been called on a shipment
with status ‘Allocated’, the status for that shipment is
changed to ‘Printed’.
Shipments created by either the Pro Shipping GUI or API can be
printed by the API call. There is no limit on the number of
times the print label request can be used on a shipment,
though high numbers of reprints will be flagged to Royal Mail.
6.9.1 Request Message
URL Path:
https://api.royalmail.net/shipping/v2/{shipmentNumber}/label?o
utputFormat={format}
The operation accepts a shipment number and also the format of
the label to be returned in the URL.
Note: To use any output format other than PDF, please contact
your Customer Solutions Consultant as additional development
and testing is required for these output types.
Datastream is not a valid option. Please contact the Customer
Solutions or ShippingSupport teams who can advise you.
Parameter Max
Lengt
h
Occur
s
Data
Type
Description
shipmentNumber 13 1-1 String The shipment number of the shipment to
be printed
23rd Oct 2018 Page 41 of 60 V2.72
Parameter Max
Lengt
h
Occur
s
Data
Type
Description
outputFormat 5 0-1 String The content of the response.
If none is specified, then returns the
standard Base64 encoded PDF Label,
otherwise the following values can be
set:
PDF: returns Base64 encoded PDF Label.
This is set by default. To enable other
format options below, you should
request the Customer Solutions team to
configure these other options under
your API login account.
DSPDF: returns both the data stream and
the Base64 Encoded PDF Label.
PNG: returns Base64 Encoded PNG images
of the 2D Data Matric and 1D Linear
Barcode. This is not an image of the 6
x 4 inch label.
DSPNG: returns both the data stream and
the Base64 Encoded PNG images of the 2D
Data Matric and 1D Linear Barcode.
Table 13 – Print Label Request Message
6.9.2 Response Message
A successful response will be returned as a HTTP status code
of 200 (Ok) with the label data in the response body JSON
payload with the field values described below.
Field Max
Lengt
h
Occur
s
Data
Type
Description
label N/A 0-1 Stri
ng
Label in PDF format and Base64
encoded
labelImages N/A 0-1 Obje
ct
Container for Base64 Encoded PNG
Images
labelImages.image1DB
arcode
N/A 1-1 Stri
ng
Base64 Encoded PNG Image of the 1D
Linear Barcode
n.b. This field will be empty for
non-barcoded services
labelImages.image2DM
atrix
N/A 1-1 Stri
ng
Base64 Encoded PNG Image of the 2D
Data Matrix
format 5 0-1 Stri
ng
The format of the response as
requested in the outputFormat URL
query parameter i.e. PDF/
DSPDF/PNG/DSPNG
labelData N/A 0-1 Obje
ct
Object containing label data fields.
labelData.upuCode 4 0-1 Stri
ng
Always “JGB”
labelData.informatio
nTypeID
1 0-1 Stri
ng
Always 6
labelData.versionID 1 0-1 Stri
ng
Always 1
labelData.format 2 0-1 Stri
ng
Dependant on Service Format selected
labelData.mailType 1 0-1 Stri
ng
Depends on what service was selected
e.g. Inland Large Letter
23rd Oct 2018 Page 42 of 60 V2.72
Field Max
Lengt
h
Occur
s
Data
Type
Description
labelData.itemID 8 0-1 Stri
ng
Unique Item ID for shipment which is
same as received in response to a
Create shipment unless Offline API is
set. If Offline API is used, the
response will be 8 character hex,
irrespective of the length of the
Item ID (8 hex or 21 character) Item
ID in the Create Shipment request.
labelData.checkDigit 1 0-1 Stri
ng
System Calculated value
labelData.itemWeight 7 0-1 Stri
ng
Shipment/Item Weight
labelData.weightType 1 0-1 Stri
ng Dependant on Service selected i.e. g,
kg etc.
labelData.product 5 0-1 Stri
ng Dependant on Service Reference
selected
labelData.trackingNu
mber
13 0-1 Stri
ng 1D Linear Barcode for shipment which
is the same as shipment number
received in response to a Create
Shipment request
labelData.destinatio
nPostcodeDPS
2 0-1 Stri
ng The post/pin code for the
destination.
labelData.returnToSe
nderPostcode
9 0-1 Stri
ng Post/Pin code for the sender for
returns
labelData.requiredAt
Delivery
1 0-1 Stri
ng If a signature is required, the value
will be S, otherwise blank.
labelData.buildingNu
mber
4 0-1 Stri
ng
Building Number (Label)
labelData.buildingNa
me
35 0-1 Stri
ng
Building Name (Label)
labelData.dateOfShip
ment
6 0-1 Stri
ng
Provisional Date Of Shipment. In
format 'YYYY-MM-DD'.
recipientAddress N/A 0-1 Obje
ct
Destination Recipient Address Details
(Label).
See Common Data Type Section 10.110.2
for further details.
recipientContact N/A 0-1 Obje
ct
Destination Recipient Contact Details
(Label).
See Common Data Type Section 10.2
for further details.
Table 14 – Print Label Response Message
6.9.3 Example Data
The following examples shows the HTTP request and successful
response messages for printing a PDF or a DSPNG label.
Print PDF Label Request
PUT https://api.royalmail.net/shipping/v2/TTT000441351GB/label?outputFormat=PDF
HTTP/1.1
X-IBM-Client-Id: a77f6e62-d4c5-4421-9af7-ba8fd3ed6eff
X-IBM-Client-Secret: C8rG0uG5gI3hK3tR3iW6lR0sY0kE1pG8wU3nQ4mA0xP0kB6aU7
X-RMG-Auth-Token:
eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjU4NzQ3MjQsImlhdCI6MTUyNTg2MDMyNCwidXNlcklkIjoiSE
9VTlNMT1cxIiwicGFzc3dvcmQiOiJyWWJHbUZqb3kzNU85M2xia01zazFwbmVpSVE9In0.D662-
SDHQxP1ZqUOc9JHmOIW96ICV0Z-Co8eYRZiSwU
23rd Oct 2018 Page 43 of 60 V2.72
Print PDF Label Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"label":
"JVBERi0xLjYKJeTjz9IKMSAwIG9iagpbL1BERi9JbWFnZUIvSW1hZ2VDL0ltYWdlSS9UZXh0XQplbmRvYm
oKNCAwIG9iago8PC9MZW5ndGggNSAwIFIKL0ZpbHRlci9GbGF0ZURlY29kZQo+PgpzdHJlYW0KeJwDAAAAA
AEKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjgKZW5kb2JqCjYgMCBvYmoKPDwv+fr/xAAfAQADAQEBAQEB
AQEBAAAAAAAAAQIDBAUGBwgJCgv/xAC1EQACAQIEBAMEBwUEBAABAncAAQIDEQQFITEGEkFRB2FxEyIygQg
UQpGhscEJIzNS8BVictEKFiQ04SXxFxgZGiYnKCkqNTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3
R1dnd4eXqCg4SFhoeIiYqSk5SVlpeYmZqio6SlpqeoMCBSCi9JbmZvIDMyIDAgUgovSURbPDZDM0VCNEREO
EE2OTNEMTVDQUE4NkRCODJCNTc2MTIzPjw2QzNFQjRERDhBNjkzRDE1Q0FBODZEQjgyQjU3NjEyMz5dCj4+
CnN0YXJ0eHJlZgoxMzI1OTYKJSVFT0YK",
"format": "PDF"
}
Print DSPNG Label Request
PUT https://api.royalmail.net/shipping/v2/TTT000441351GB/label?outputFormat=DSPNG
HTTP/1.1
X-IBM-Client-Id: a77f6e62-d4c5-4421-9af7-ba8fd3ed6eff
X-IBM-Client-Secret: C8rG0uG5gI3hK3tR3iW6lR0sY0kE1pG8wU3nQ4mA0xP0kB6aU7
X-RMG-Auth-Token:
eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjU4NzQ3MjQsImlhdCI6MTUyNTg2MDMyNCwidXNlcklkIjoiSE
9VTlNMT1cxIiwicGFzc3dvcmQiOiJyWWJHbUZqb3kzNU85M2xia01zazFwbmVpSVE9In0.D662-
SDHQxP1ZqUOc9JHmOIW96ICV0Z-Co8eYRZiSwU
Print DSPNG Label Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"labelImages": {
"image1DBarcode":
"iVBORw0KGgoAAAANSUhEUgAAAfUAAABvAgMAAACIrLETAAAADFBMVEXMzMz///8AAAD/AADq3YbvAAAACX
BIWXMAAB7pAAAe6QF1y32iAAAACXZwQWcAAAH1AAAAbwAUn0l/AAAAjUlEQVRo3u3NUQ3AMAgFwJlkH5UwF
TNRCf0YKgergQm4hJAWXrgj1xVjRlzPyCei+plZ3zNn5qxVz0dWrHp09bC2Feu+olfRvSY7XIHswOyDu0bf
jH38e3/5+8Dj8Xg8Ho/H4/F4PB6Px+PxeDwej8fj8Xg8Ho/H4/F4PB6Px+PxeDwej8fj8Xg8/hf/AgOtTBV
IW17PAAAAJXRFWHRkYXRlOmNyZWF0ZQAyMDE1LTA4LTIwVDEzOjMwOjAyKzAyOjAwaNwXVgAAACV0RVh0ZG
F0ZTptb2RpZnkAMjAxNS0wOC0yMFQxMzozMDowMiswMjowMBmBr+oAAAAASUVORK5CYII=",
"image2DMatrix":
"iVBORw0KGgoAAAANSUhEUgAAABQAAAAUAQAAAACl8iCgAAAAAmJLR0QAAd2KE6QAAAAJcEhZcwA
AHukAAB7pAXXLfaIAAAAJdnBBZwAAABQAAAAUAKM7KtEAAAA1SURBVAjXYzA2NmAAYfvzDGDMYP8B
jI0PHABj5jMfwJjnDAMYGxt8AGObwwxgzPzfAIyhAACHQRVDZvCDogAAACV0RVh0ZGF0ZTpjcmVh
dGUAMjAxNS0wOC0yMFQxMzozMDowMyswMjowMM6rHOIAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTUt
MDgtMjBUMTM6MzA6MDMrMDI6MDC/9qReAAAAAElFTkSuQmCC"
},
"format": "DSPNG",
"labelData": {
"upuCode": "JGB",
"informationTypeID": "6",
"versionID": "1",
"format": "P",
23rd Oct 2018 Page 44 of 60 V2.72
"mailType": "Inland Parcel",
"itemID": "459",
"checkDigit": "3",
"itemWeight": "250",
"weightType": "g",
"product": "CRL_1",
"trackingNumber": "TTT000527313GB",
"destinationPostcodeDPS": "YT6 1BB",
"returnToSenderPostcode": "LU3 1SY",
"requiredAtDelivery": "S",
"buildingNumber": "25",
"dateOfShipment": "2015-08-20"
},
"recipientAddress": {
"buildingName": "One Broadgate",
"buildingNumber": "1",
"addressLine1": "Addressline 1",
"addressLine2": "Addressline 2",
"addressLine3": "Addressline 3",
"stateOrProvince": "NewYork",
"postTown": "London",
"county": "NY",
"postCode": "EC2M 2QS",
"country": "GB"
},
"recipientContact": {
"name": "Miss A Jones",
"complementaryName": "Acme Ltd",
"telephoneNumber": "09784456354",
"electronicAddress": "[email protected]"
}
}
23rd Oct 2018 Page 45 of 60 V2.72
6.10 Print Documents
The Print Documents operation allows you to request an
International Document (Based on HMRC export requirements) in
Base64 encoded PDF format. Printing International Documents
is an optional step in sending a shipment. Note: this
operation cannot be used with Average Weight International
products where the End of Day Average weight option has been
turned on (by Royal Mail for you)
6.10.1 Request Message
URL Path:
https://api.royalmail.net/shipping/v2/shipments/{shipmentNumbe
r}/documents
The international shipment number for which documents are to
be created is passed as a parameter in the URL.
The request payload fields below specifies the type and number
of documents to be printed.
Parameter/Fie
ld
Max
Lengt
h
Occur
s
Data
Type
Description
shipmentNumber 13 1-1 String The international shipment number for
which the documents to be printed are
for.
documentName 4 1-1 String Mandatory: The type of the document to
output. Valid values are CN22, CN23 and
CI (for Commercial Invoice).
documentCopies 1 0-1 Number Number of copies of the international
documents within the single base64
encoded PDF output. Valid values: 1 or
3. 3 for Commercial Invoice Only.
Table 15 – Print Documents Request Message
6.10.2 Response Message
A successful response will be returned as a HTTP status code
of 200 (Ok) with the label data in the response body JSON
payload with the field values described below.
Field Max
Lengt
h
Occur
s
Data
Type
Description
internationalDocumen
t
N/A 1-1 Stri
ng
Base64 encoded PDF international
document.
Table 16 – Print Documents Response Message
6.10.3 Example Data
The following example shows the HTTP request and successful
response messages for a successfully printed document.
Print Documents Request
23rd Oct 2018 Page 46 of 60 V2.72
PUT https://api.royalmail.net/shipping/v2/shipments/TTT000441351GB/documents
HTTP/1.1
X-IBM-Client-Id: a77f6e62-d4c5-4421-9af7-ba8fd3ed6eff
X-IBM-Client-Secret: C8rG0uG5gI3hK3tR3iW6lR0sY0kE1pG8wU3nQ4mA0xP0kB6aU7
X-RMG-Auth-Token:
eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjU4NzQ3MjQsImlhdCI6MTUyNTg2MDMyNCwidXNlcklkIjoiSE
9VTlNMT1cxIiwicGFzc3dvcmQiOiJyWWJHbUZqb3kzNU85M2xia01zazFwbmVpSVE9In0.D662-
SDHQxP1ZqUOc9JHmOIW96ICV0Z-Co8eYRZiSwU
Print Documents Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"label":
"JVBERi0xLjYKJeTjz9IKMSAwIG9iagpbL1BERi9JbWFnZUIvSW1hZ2VDL0ltYWdlSS9UZXh0XQplbmRvYm
oKNCAwIG9iago8PC9MZW5ndGggNSAwIFIKL0ZpbHRlci9GbGF0ZURlY29kZQo+PgpzdHJlYW0KeJwDAAAAA
AEKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjgKZW5kb2JqCjYgMCBvYmoKPDwv+fr/xAAfAQADAQEBAQEB
AQEBAAAAAAAAAQIDBAUGBwgJCgv/xAC1EQACAQIEBAMEBwUEBAABAncAAQIDEQQFITEGEkFRB2FxEyIygQg
UQpGhscEJIzNS8BVictEKFiQ04SXxFxgZGiYnKCkqNTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3
R1dnd4eXqCg4SFhoeIiYqSk5SVlpeYmZqio6SlpqeoMCBSCi9JbmZvIDMyIDAgUgovSURbPDZDM0VCNEREO
EE2OTNEMTVDQUE4NkRCODJCNTc2MTIzPjw2QzNFQjRERDhBNjkzRDE1Q0FBODZEQjgyQjU3NjEyMz5dCj4+
CnN0YXJ0eHJlZgoxMzI1OTYKJSVFT0YK"
}
23rd Oct 2018 Page 47 of 60 V2.72
6.11 Create Manifest
The Create Manifest operation allows you to submit to Royal
Mail details of all of the items that will be despatched on
the current date. Refer to the Create Shipment call,
shippingDate field to create shipments for future dates and
the Update Shipment call, shippingDate field to alter the
shipment date or the Cancel Shipment call to exclude shipments
from the manifest. Once the Create Manifest operation has been
called, all shipments that have status ‘Printed’ will be set
to status ‘Manifested’ and it will no longer be possible to
update or cancel them.
Manifests can be created by Service Reference or by Service
Code, or if neither is specified then all shipments that have
status ‘Printed’ will be included (N.B. Tracked Returns are
not included in any part of the manifesting process).
The operation creates the PDF manifest in an asynchronous
operation and may not be immediately available for printing
using the Print Manifest operation.
6.11.1 Request Message
URL Path: https://api.royalmail.net/shipping/v2/manifest
Fields in the request message are shown the table below.
Element Max
Lengt
h
Occur
s
Data
Type
Description
serviceOccurence