Intelligent Shipper API - FAQ

  1. How do I create shipments to BFPO addresses?
    The following steps must be followed in order to create a shipment to a BFPO address:
    1. destinationPostcode: You will need to enter a BFPO postcode in the field for destination postcode. A list of valid BFPO post codes can be found on
    2. Countrycode: Enter to GB
    3. Destination town: Enter ‘BFPO’ followed by ‘unit number’ (eg BFPO 19)
    4. Enter the correct service code for the BFPO service you want to use. For the full list of the BFPO services we offer please refer to Royal Mail Service Matrix.
  2. Why do I not receive CN22 documents for Royal Mail International shipments?
    If Intelligent Shipper has been configured to return a CN23 via the API, then the createShipmentResponse will return a CN23 along with the shipment label for international shipments. A CN23 can also be produced by using the printDocumentRequest – setting in the request to “CN” will produce a CN23 document. Intelligent Shipper will not return the CN22 document, as the CN23 provides all the information needed to satisfy the requirements of a CN22. Providing the required Customs Documentation and information required to populate these documents is ultimately the responsibility of the posting customer.
  3. I am shipping to Channel Islands via Royal Mail, how can I get customs documentation?
    Channel Islands are treated as domestic shipments by Royal Mail. If the destination country code for shipments to Isle of Man, Guernsey and Jersey is GB Intelligent Shipper will create the outbound label only; customs documentation will not be included with the label. If you need customs documentation, you can either request it by calling our printDocuments service or change the country code to IM for Isle of Man, GG for Guernsey and JE for Jersey, and CN documentation will be printed with the label.
  4. Why isn’t my customer receiving SMS/Email notifications for Royal Mail tracked services?
    Please make sure you are using one of the email and SMS enhancement codes listed in Appendix 1 of Shipping Integration API – Multipiece Shipment Bookings Appendices in the createShipmentRequest, and that you are using Royal Mail Tracked or Special Delivery services.
  5. Does the <exportLicense> field get validated by Intelligent Shipper? Would it throw an error to prevent shipments with incorrect declaration, if it was filled with the wrong information?
    <exportLicense> is an optional field in Intelligent Shipper, so the only validation that will be done on the field is that when a value is provided it’s within the maximum field length. Intelligent Shipper won’t validate that the field is populated when an export license is required for a shipment, because we don’t have any logic in the system to say when an export license is required – the customer is responsible for knowing whether an export declaration is needed or not for the goods they are shipping. As the API document says, this is mostly needed when shipping goods for military purposes, but customers should be able to find more information about it on the UK Government website (
    Though <exportLicense> is an optional field, if the customer populates it with true then they should provide an export declaration with the shipment – this is because the data may be sent onto the carrier, depending on whether the carrier has a field to capture this information. So, the physical customs documents the customer provides needs to match up with the electronic data.
  6. What <transactionId> field is? What should it include?
    <transactionId> field can be populated with anything you want. There is a limit of 32 characters for this field. It is not needed to change it for every request. It can always remain the same.
  7. What does C, N and D stand for in Data Type column of Intelligent Shipper API - Multipiece Shipment Bookings?
    C, N and D are defining the type of field. C = character (alphanumeric), N= numeric, D = date. For numbers written in the format N-7,3 = this is a way of expressing decimals in SQL. the number before the comma is the total length and the number after the comma is the number of digits after the decimal place. So e.g. 7,3 means there can be 4 digits before the decimal places and 3 digits after
  8. Why am I getting "Error deserializing XML..." message? 
This error message is returned when the request is created not according to the API specs. One of the possible reasons may also be special characters. Our API does not accept characters such as & < > " and ' 
The are to be replaced by the below:
Special Character To be replaced by:
& &amp;
< &lt;
> &gt;
" &quot;
' &apos;


9. Why am I getting 'The service is not valid for these shipment contents to this destination' 

This error message is returned when either the service is not added to that customers Royal Mail contract, so it is not valid for that customer, or for multi-carrier if the service has not been mapped correctly, therefore making it unavailable.