JSON Request Structure and Format
The International Shipment request JSON message format and structure is the same as for the domestic shipment message, however it is mandatory to complete the customs information and the reason for export, for an international shipment.
UK to NI shipments now require customs documentation.
Note: where a section is referred to as a “sub-section” – this means that it is a section of data that is nested within another for the message.
This section summarises the contents of the shipment being sent. It is important to provide accurate information, to ensure correct handling for the shipment.
Within the shipment Information element the information on the date, format of labels, currency and measurement units to be applied to the items within the shipment. The shipping API can thereby validate the data contained in this section accordingly.
The fields, data types and conditions that will be validated for in the Shipment Information section are detailed below.
M/C/O Column determines whether the data element is Mandatory, Optional, or Conditional (Conditional data elements become mandatory based on relevant circumstances)
This section details the shippers address and contact details.
Within the Shipper element of the message, the user needs to send information on where the shipment is being despatched from. The shipping API can thereby validate the data contained in this section accordingly.
For a create shipment request, this sub-section is embedded within the shipper, destination and return to sender sections. Depending on where the section is in the message dictates the type of address that is being passed. For example, if the Address section is within the shipper part of the message, then the Shipping API will determine that this is a shipper address. The fields, data types and conditions that will be validated for in the address section are detailed below.
This section details the delivery address and contact details for the shipment recipient. It is the shipper’s responsibility to provide accurate and concise information to ensure accurate responses.
Within the Destination element of the message, the user needs to send recipient information. This then tells the receiving system that it is going to receive details of a shipment and this section will contain the destination data, it can thereby validate the data contained in this section accordingly.
This section details the service levels and the service enhancements that are to be applied to the shipment. For more information on the Royal Mail shipping services and enhancements available, please refer to the Royal Mail shipping website.
This section lists all of the service enhancements that are able to be applied to the shipment. It is possible to provide up to 4 service enhancements for each shipment.
For a full and up to date list of Service Enhancements, please refer to the Royal Mail Shipping website.
This section is used to define the type, dimension and weight details of the individual packages that are to be included in the shipment.
This nested sub-section is where the size dimensions of the individual packages are defined.
This section details the contents of the shipment – there can be many Items in one shipment.
This section is mandatory if you are sending an international shipment. In addition, you will need to provide the relevant customs documentation when you despatch your shipment.
A shipment is considered international if the shipper country and destination country are not the same. UK to NI shipments now require custom documents.
This section details the location the shipment/items should be returned to, should they not be able to be delivered successfully.
This section is only required if the return to sender address is different from those details supplied in the shipper section. If this information is not provided then the shipper address will be used by default as the return to sender address.
See Subsection 3
Updated 9 months ago