JSON Request Structure and Format
For further details on the standard JSON message formatting, please refer to the Shipping API JSON Formatting Rules.
The Domestic Shipment request JSON message is comprised of the following listed sections.
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
Shipment Information section:
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 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).
Shipper section:
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.
The fields, data types and conditions validated for in the shippers section are detailed below.
Address sub-section:
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 validated for in the address section are detailed below.
Destination section:
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.
The fields, data types and conditions validated for in the Destination section are detailed below.
Carrier Specifics section:
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.
The fields, data types and conditions validated for in the CarrierSpecifics section as detailed below.
Service Enhancement sub-section:
This section lists all the service enhancements 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.
The fields, data types and conditions validated for in the ServiceEnhancements section as detailed below.
Packages section:
This section is used to define the type, dimension and weight details of the individual packages that are to be included in the shipment.
The fields, data types and conditions validated for in the packages sub-section as detailed below.
Dimensions sub-section:
This nested sub-section is where the size dimensions of the individual packages are defined.
The fields, data types and conditions validated for in the dimensions sub-section are detailed below.
Item Information section:
This section details the contents of the shipment – there can be many Items in one shipment.
The fields, data types and conditions validated for in the Item Information section as detailed below.
Return to Sender section:
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.
The fields, data types and conditions validated for in the Item Information section as detailed below
Updated 9 months ago