v1

latestOpenAPI 3.0.12026-07-242073551.1 MB
Shipments

Create Shipment

Create a new Royal Mail shipment by submitting the shipment details in your request and returning an image of the shipping label in PDF, PNG, or ZPL format.

post/v4/shipments/rm

Request body

Example request

{
  "ShipmentInformation": {
    "ServiceCode": "CRL1",
    "DescriptionOfGoods": "Clothing",
    "DeclaredValue": 98.99,
    "DeclaredWeight": 1.5,
    "CurrencyCode": "GBP",
    "ContainerId": "South East"
  },
  "Shipper": {
    "ShippingAccountId": "453",
    "ShippingLocationId": "938",
    "Reference1": "REF-12345-GB",
    "Reference2": "EXTERNALREF-12345-GB",
    "DepartmentNumber": "0123456789",
    "EoriNumber": "GB 123 4567 89 000",
    "VatNumber": "GB 123 4567 89",
    "Address": {
      "AddressId": "John Brown Default",
      "ContactName": "Jane Doe",
      "CompanyName": "My Company Ltd.",
      "ContactEmail": "jane@example.com",
      "ContactPhone": "07123887422",
      "Line1": "Brown Cottage",
      "Line2": "10 Sky Lane",
      "Line3": "Hills End",
      "Town": "Christchurch",
      "Postcode": "TW20 0HJ",
      "County": "Surrey",
      "CountryCode": "GB",
      "What3Words": "brick.space.employ"
    }
  },
  "Destination": {
    "EoriNumber": "GB 123 4567 89 000",
    "VatNumber": "GB 123 4567 89",
    "Address": {
      "AddressId": "John Brown Default",
      "ContactName": "Jane Doe",
      "CompanyName": "My Company Ltd.",
      "ContactEmail": "jane@example.com",
      "ContactPhone": "07123887422",
      "Line1": "Brown Cottage",
      "Line2": "10 Sky Lane",
      "Line3": "Hills End",
      "Town": "Christchurch",
      "Postcode": "TW20 0HJ",
      "County": "Surrey",
      "CountryCode": "GB",
      "What3Words": "brick.space.employ"
    }
  },
  "CarrierSpecifics": {
    "ServiceLevel": "01",
    "EbayVtn": "ebay1234ABC",
    "ServiceEnhancements": [
      {
        "SafeplaceLocation": "Front Porch"
      }
    ],
    "OfflineBarcode": {
      "PackageOccurrence": 1,
      "TrackingNumber": "TT123456789GB",
      "UniqueId": "3A01234561234568AE7C7"
    },
    "OfflineBarcodes": [
      {
        "PackageOccurrence": 1,
        "TrackingNumber": "TT123456789GB",
        "UniqueId": "3A01234561234568AE7C7"
      }
    ],
    "PreAllocatedTrackingNumber": "TT123465789GB",
    "TermsOfDelivery": "DTP",
    "Importer": {
      "Address": {
        "AddressId": "John Brown Default",
        "ContactName": "Jane Doe",
        "CompanyName": "My Company Ltd.",
        "ContactEmail": "jane@example.com",
        "ContactPhone": "07123887422",
        "Line1": "Brown Cottage",
        "Line2": "10 Sky Lane",
        "Line3": "Hills End",
        "Town": "Christchurch",
        "Postcode": "TW20 0HJ",
        "County": "Surrey",
        "CountryCode": "GB",
        "What3Words": "brick.space.employ"
      },
      "EoriNumber": "GB987654321224455",
      "VatNumber": "AU777444411"
    },
    "EnhancedCustomsInformation": [
      {
        "SkuCode": "C604-25-035",
        "LicenseNumber": "AB123456789",
        "CertificateNumber": "DFG9876543",
        "OriginPreferenceCode": 300
      }
    ]
  },
  "Packages": [
    {
      "PackageOccurrence": 1,
      "DeclaredWeight": 1.5,
      "DeclaredValue": 98.99,
      "Dimensions": {
        "Length": 35,
        "Width": 25,
        "Height": 20
      }
    }
  ],
  "Items": [
    {
      "SkuCode": "C604-25-035",
      "PackageOccurrence": 1,
      "Quantity": 1,
      "Description": "White Tee-shirt",
      "Value": 98.99,
      "Weight": 145,
      "ImageURL": "https://yourcompany.com/images/product.jpg",
      "HSCode": "6109100010",
      "CountryOfOrigin": "GB",
      "SupplementaryUnits": 12.2
    }
  ],
  "Customs": {
    "ReasonForExport": "Sale of Goods",
    "PreRegistrationNumber": "0123456789",
    "PreRegistrationType": "GST",
    "ShippingCharges": 55.82,
    "OtherCharges": 32,
    "QuotedLandedCost": 82.74,
    "Airn": "231.002.999-00"
  },
  "ReturnToSender": {
    "Address": {
      "AddressId": "John Brown Default",
      "ContactName": "Jane Doe",
      "CompanyName": "My Company Ltd.",
      "ContactEmail": "jane@example.com",
      "ContactPhone": "07123887422",
      "Line1": "Brown Cottage",
      "Line2": "10 Sky Lane",
      "Line3": "Hills End",
      "Town": "Christchurch",
      "Postcode": "TW20 0HJ",
      "County": "Surrey",
      "CountryCode": "GB",
      "What3Words": "brick.space.employ"
    }
  }
}

Response

The shipment was created successfully.

ConsignmentShipmentIdstring uuid nullable

A unique identifier assigned to the shipment by the carrier. This ID is useful for tracking and managing the shipment throughout its transit journey and can be used in future queries or to reference the specific shipment. <br /> <br />Note: This field is only populated if a consignment service was used in the request.

ConsignmentTrackingNumberstring nullable

A unique identifier assigned to the entire consignment shipment by the carrier. This number allows shippers and recipients to track the status and location of the entire shipment throughout its transit. It is useful for monitoring progress, ensuring timely delivery, and addressing any issues that may arise during transportation. <br /> <br />Note: This field is only populated if the service is a consignment service.

ConsignmentCarrierTrackingUrlstring uri nullable

A URL link provided by the carrier that allows the shipper and recipients to access real-time tracking information about the consignment shipment. This link directs users to the carrier's website where they can view detailed status updates and current location of the shipment. <br /> <br />Note: This field is only populated if this feature is available and the service is a consignment service.

Labelsstring nullable

Returns the generated shipping labels for the shipment. This field is populated only if the requested action was "Process." The labels include the necessary barcodes and shipping information required for effective transit and delivery of the packages.<br/><br/>Note: This field has the following reservations: <br/><ul><li>This field returns the labels only if the ReturnLabelsAtPackageLevel field is set to false.</li><li>In addition to the shipping label, this field also returns the ID8000 label for Class 9 hazardous products—provided that the PrintId8000Label field in the request parameters is set to true.</li></ul><br/>

LabelFormat'PDF' | 'PNG' | 'DATASTREAM' | 'ZPL203DPI' | 'ZPL300DPI' | 'PDF4X3' | 'PNG4X3'

Specifies the format of the shipping label that will be returned in the createShipment response. <br />The following are the valid values: <br /><ul><li>PDF - returns a Base64-encoded PDF</li><li>PNG - returns a Base64-enconded PNG</li><li>ZPL203DPI - returns Base 64 encoded text for Zebra printer at 203 DPI</li><li>ZPL300DPI - returns Base 64 encoded text for Zebra printer at 300 DPI</li><li>DATASTREAM - returns the label elements such as tracking URL, barcode number, 2D barcode image etc. for the label to be created in your own system, rather than returning a label image</li><li>PDF4X3 - returns a Base64-encoded 4x3 format PDF</li><li>PNG4X3 - returns a Base64-enconded 4x3 format PNG</li></ul>

Documentsstring nullable

This object is only returned if the shipment is dutiable and the requested action was "Process." This object includes any requisite documentation necessary for customs clearance and compliance, ensuring that all regulatory requirements are met for international shipments.

DocumentFormat'PDF' | 'PNG' | 'ZPL203DPI' | 'ZPL300DPI'

Specifies the format in which the documents related to the shipment are provided. For example, a Base 64 encoded PDF, PNG or ZPL203DPI, and ZPL300DPI. <br /> <br />This format is crucial for ensuring that the documents can be easily accessed, printed, and utilised during shipping and customs processes.

Example response

{
  "ConsignmentShipmentId": "c4e60776-288f-464e-b35b-ff0f3252c0f0",
  "ConsignmentTrackingNumber": "DF12384739GB",
  "ConsignmentCarrierTrackingUrl": "http://shipmentcarrier.com/tracking/DF12384739GB",
  "Packages": [
    {
      "TrackingNumber": "TT123456789GB",
      "CarrierDetails": {
        "UniqueId": "3A01234561234568AE7C7",
        "PartnerDetails": {
          "PartnerName": "FedEx",
          "PartnerCode": "FEDEX",
          "PartnerTrackingNumber": "794953535000",
          "PartnerTrackingUrl": "https://www.fedex.com/en-gb/tracking.html"
        },
        "DataStreamDetails": {
          "Primary2DBarcodeImage": "iVBORw0KGgoAAAANSUhE ...…GgAAABoAQMAAAAn0ifiAAAA",
          "Primary2DBarcodeData": "iVBORw0KGgoAAAANSUhE ...…GgAAABoAQMAAAAn0ifiAAAA",
          "FormattedUniqueId": "3A-070 338 6001-000 0B2 000",
          "GazetteerCodes": {
            "Part1": "L55",
            "Part2": "G43",
            "Part3": "AAA",
            "Part4": "000"
          },
          "SecondaryRoutingCode": "NORW",
          "Primary1DBarcodeImage": "iVBORw0KGgoAAAANSUhE ...…GgAAABoAQMAAAAn0ifiAAAA",
          "Primary1DBarcodeData": "HF123456783GB",
          "HighVolumeBarcodeImage": "iVBORw0KGgoAAAANSUhE ...…GgAAABoAQMAAAAn0ifiAAAA",
          "HighVolumeBarcodeData": "*SW115QZ*"
        }
      },
      "ShipmentId": "c4e60776-288f-464e-b35b-ff0f3252c0f0"
    }
  ],
  "Documents": "iVBORw0KGgoAAAANSUhEUgAA ... A4QAAAXcCAYAAAB6Q0CbAAAAAXNSR0IArs4"
}