shipping api spec v2 - royal mail...23rd oct 2018 page 6 of 60 v2.72 integrate with royal mail, and...

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

Print

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

Print

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


POST /manifest Response ( manifestBatchNumber )

PUT /{shipmentNumber}/label Request

Customer App

Royal Mail

POST /shipments Request,PUT /{shipmentNumber} Request


PUT /manifest Request

( token, offlineShipment elements omitted in request )

POST /shipments Request,PUT /{shipmentNumber} Response

( itemID (2D) for each shipment and shipmentNumber (1D) )


( token, shipmentNumber, outputFormat = DSPDF / PNG / DSPNG )

( depends on output Format selected in print Label) PUT /{shipmentNumber}/label Response


End of Day (EOD)

( Sales Order Summary / manifest in base 64 encoded PDF format )

( token, manifestBatchNumber )


Output format of PNG or DSPNG requires the customer to generate the label template to Royal Mail requirements from their own system.



PUT /shipments/{shipmentNumber}/documents Request ( token, shipmentNumber, documentName = CN22 / CN23 / CI )



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.


POST /manifest Response ( manifestBatchNumber including manifest in base 64 encoded

PDF format)

Customer App

Royal Mail

POST /shipments Request


( token, offlineShipment elements omitted in request )

POST /shipments Response ( itemID (2D) for each shipment and shipmentNumber (1D) including

base 64 encoded PDF label)



End of Day (EOD)




PUT /shipments/{shipmentNumber}/documents Request ( token, shipmentNumber, documentName = CN22 / CN23 / CI )



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.


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





Data..

service.type 4 1-1 String Mandatory. The system Service Type

of the shipment. For the list of





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





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


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.


nt[].itemID


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.


nt[].status


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.



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


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


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.


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.


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


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.


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


parcels[].height N/A 0-1 Measu

remen

t

Height dimension of

shipment, , Must in 'cm'.

See Common Data Type Section


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


nitQuantity

N/A 1-1 Numbe

r

Mandatory. Quantity of

content items within the

shipment.


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


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-RMG-Auth-Token:

eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjU4NzQ3MjQsImlhdCI6MTUyNTg2MDMyNCwidXNlcklkIjoiSE

9VTlNMT1cxIiwicGFzc3dvcmQiOiJyWWJHbUZqb3kzNU85M2xia01zazFwbmVpSVE9In0.D662-


{

"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",



"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


{

"completedShipments": [

{

"shipmentItems": [

{

"shipmentNumber": "HY188980152GB

23rd Oct 2018 Page 34 of 60 V2.72

}

],


"name": "Joe Bloggs",

"complementaryName": "Acme Ltd",


"email": "[email protected]"

},


"buildingName": "Amphitheatre",

"buildingNumber": 600,

"addressLine1": "Parkway Mountain View",




"postTown": "Mountain View",

"county": "CA",

"postCode": "94043",

"countryCode": "US"

},

"senderReference": "DS324354545",

"departmentReference": "DEPTREF",

"customerReference": "CUSTOMERREF",

"safePlace": "Porch",

"internationalInfo": {

"parcels": [

{

"weight": {


"value": 25

},

"length": {

"unitOfMeasure": "cm",

"value": 55

},

"height": {


"value": 20

},

"width": {


"value": 30

},

"purposeOfShipment": "31",

"explanation": "Toys",

"invoiceNumber": "12787578435",

"exportLicenseNumber": "6465464565",

"certificateNumber": "123243423",

"contentDetails": [

{

"countryOfManufactureCode": "US",

"manufacturersName": "Bloggs Corp",

"description": "Toys",

"unitWeight": {


"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


{

"completedShipments": [

{

"shipmentItems": [

{

"shipmentNumber": "HY188980152GB",

"itemID": "1000076",

"status": "Printed",

"validFrom": "2015-02-09T09:52:06.000+02:00",

"label":

"JVBERi0xLjQKJdP0zOEKMSAwIG9iago8PAovQ3JlYXRpb25EYXRlKEQ6MjAxODA5M……..="

}

],

"weight": {


"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.


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.



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-RMG-Auth-Token:




{


"buildingName": "Beech House",


"addressLine1": "Updated AddressLine 1",

"addressLine2": "Updated AddressLine 2",


"postTown": "Brighton",

"county": "NY",

"postCode": "BN3 3JA"

}

}

Update Shipment Response

HTTP/1.1 200 OK


{

"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.


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



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-RMG-Auth-Token:


23rd Oct 2018 Page 39 of 60 V2.72



Cancel Shipment Response

HTTP/1.1 200 OK


{

"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.


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



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


recipientContact N/A 0-1 Obje

ct

Destination Recipient Contact Details

(Label).



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-RMG-Auth-Token:




23rd Oct 2018 Page 43 of 60 V2.72

Print PDF Label Response

HTTP/1.1 200 OK


{

"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-RMG-Auth-Token:




Print DSPNG Label Response

HTTP/1.1 200 OK


{

"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",


"dateOfShipment": "2015-08-20"

},


"buildingName": "One Broadgate",


"addressLine1": "Addressline 1",




"postTown": "London",

"county": "NY",

"postCode": "EC2M 2QS",

"country": "GB"

},


"name": "Miss A Jones",

"complementaryName": "Acme Ltd",


"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)


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



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-RMG-Auth-Token:




Print Documents Response

HTTP/1.1 200 OK


{

"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.


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