---
title: "Create Shipment"
method: POST
path: "/v4/shipments/rm"
tags: ["Shipments"]
---

# Create Shipment

`POST /v4/shipments/rm`

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.

## Request body

- RoyalMailShipmentRequestCarrierSpecificsRoyalMailPackageRoyalMailLabelFormatCreateShipmentRequest — Create Shipment Request
  - `ShipmentInformation` RoyalMailLabelFormatShipmentInformation, required — Used to provide shipment-level information such as service code, content type, general goods description, total shipment weight and value etc.
    - `Action` 'Process' | 'Create' | 'Allocate' — Indicates the operation to be performed for the shipment, determines the shipment status that is set on shipment creation and whether a shipment tracking number and labels are generated. <br /> <br />Valid values are: <br /><ul><li>**Process:** Creates a shipment tracking number, generates and prints a label for each package in the shipment, and returns the labels in the **createShipment** response. With this action, the shipment status is set to **Ready to Manifest**.</li><li>**Create:** Creates the shipment but does not allocate a tracking number, print the labels or return them in the **createShipment** response. The label(s) must be printed before the shipment is ready to manifest.</li><li>**Allocate:** Creates the tracking number and label but does not print the labels or return them in the **createShipment** response. The label(s) must be printed before the shipment is ready to manifest.</li></ul> <br />***Note:** By default, this field is set to Process.*
    - `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>
    - `ReturnLabelsAtPackageLevel` boolean — A boolean field that provides customers with the choice to generate labels at the package level instead of the shipment level. When set to true, the system returns labels for each individual package contained within the shipment. <br />This field is currently only supported for Royal Mail shipments. <br /> <br />***Note:** This field is ignored if the **Action** field is populated with values other than **Process**. By default, this field is set to false.*
    - `ContentType` 'NDX' | 'DOX' | 'HV', required — Defines the type of contents being shipped. This helps the carrier manage the shipment according to its content type. <br /> <br />Valid values are: <br /><ul><li>**NDX** - Non Documents</li><li>**DOX** - Documents</li><li>**HV** - Non Documents of High Value</li></ul>
    - `ServiceCode` string, required — A valid unique code identifying the service selected for the shipment's delivery and collection address, which determines pricing, delivery speed, and other service attributes.
    - `DescriptionOfGoods` string, required — A general description of the items being shipped, which may include details such as type, quantity, and specifications. This field provides clarity about the contents for customs and handling purposes.
    - `BusinessTransactionType` 'B2C' | 'B2B' | 'D2C' | 'C2B' — Specifies the nature of the commercial transaction type associated with the shipment. <br /> <br />Valid values are: <br /> <br />**B2C** - Business to Consumer <br />**B2B** - Business to Business <br />**D2C** - Direct to Consumer <br />**C2B** - Consumer to Business (that is, a returns shipment) <br /> <br />***Note:** By default, this field is set to B2C.*
    - `ShipmentDate` string, date, nullable — The scheduled date for the shipment to be shipped, which cannot be in the past and must not exceed 28 days into the future. If omitted, it defaults to the current date.<br><br />***Note:** The shipment date must be in the YYYY-MM-DD format.*
    - `DeclaredValue` number, double, nullable — The declared monetary value assigned to the shipment in the specified currency. If provided, it must equal or exceed the sum of all item values. If not provided, it defaults to the sum of all item values. <br /> <br />***Note:** For Non-Consignment Services where multiple packages are declared, use the declared value at the package level instead.*
    - `DeclaredWeight` number, double, nullable — The total weight of the shipment in the unit of measure specified in the **WeightUnitOfMeasure** field. This weight should meet or exceed the weight of all packages or items and is required for consignment services. The minimum allowed weight is 0.001 Kg and the maximum is dependent on the carrier, service, and destination. <br /> <br />***Note:** For all Non-Consignment Services, use the declared weight at the package level instead.*
    - `CurrencyCode` string, nullable — The three-letter ISO code indicating the currency in which any monetary value is specified (for example, USD, EUR). This ensures clarity for payment and invoicing purposes.<br><br />***Note:** This information is required if any monetary values other than zero are provided.*
    - `WeightUnitOfMeasure` 'KG' | 'Grams' — The unit of measure used for all weight values in the shipment, expressed in grams and kilograms, for example, **DeclaredWeight**, **ItemWeight**. This is crucial for accurately describing shipment weight. <br /> <br />***Note:** By default, this field is set to KG.*
    - `DimensionsUnitOfMeasure` 'CM' | 'MM' — The unit of measure used for all the dimensions (length, width, height) values of the packages being shipped, allowing for measurements in millimeters and centimeters. This ensures consistency in how dimensions are handled. <br /> <br />***Note:** By default, this field is set to CM.*
    - `ContainerId` string, nullable — A unique identifier assigned by the system or by you (alias) to the container in a shipment, so that the shipment can be added to the existing container when the shipment is created. <br /> <br />If a valid **ContainerId** is specified, the shipments in the request will be automatically allocated to that container upon creation. If the **ContainerId** is provided, then the **Process** action is required.<br /> <br />***Note:** The container must already exist for the same Carrier and Shipping Location as the shipment.*
  - `Shipper` Shipper, required — Used to provide shipper details such as address, contact details, VAT and EORI number etc.
    - `ShippingAccountId` string, required — A unique identifier assigned by the system (shippingAccountId) or by you (alias) to the shipping account for which the shipment is being created.
    - `ShippingLocationId` string, nullable — A unique identifier assigned by the system (shippingLocationId) or by you (alias) to the shipping location for which the shipment is being created. <br /> <br />***Note:** This field is mandatory if more than one shipping location is available for the shipping account.*
    - `Reference1` string, nullable — The shipper's reference for this shipment. This is usually the shipper's order number that is provided to the receiver when the order was made. <br /> <br />***Note:** This information may be required based on the customer account settings in the GUI.*
    - `Reference2` string, nullable — An optional field that allows for additional identifying information that assists in shipment tracking and referencing.
    - `DepartmentNumber` string, nullable — An optional field where the shipper can specify the department number associated with the shipment.
    - `EoriNumber` string, nullable — The EORI (Economic Operators Registration and Identification) number for the shipper, which must start with the ISO Alpha-2 Country Code followed by up to 15 alphanumeric characters. For Northern Ireland, it starts with XI. <br /> <br />***Note:** Make sure to provide this information here—not in the **Customs** object. This field is mandatory for B2B shipments from Great Britain to Northern Ireland.*
    - `VatNumber` string, nullable — The VAT (Value Added Tax) number for the shipper, which is required for business transactions, helping to ensure compliance with tax regulations. <br /> <br />***Note:** Make sure to provide this information here—not in the **Customs** object.*
    - `Address` ShipperAddress — The complete address of the shipper's location, consisting of multiple components including street information, locality, and so on. <br /> <br />***Note:** If this information is not provided, then the shipping location's address will be used.*
      - `AddressId` string, nullable — A unique identifier for the address. This information ensures that each address can be distinctly referenced and managed within the system. <br /> <br />***Note:** If this information is provided, then all the fields under the **Address** object are ignored and the stored address in the **Address Book** will be used.*
      - `ContactName` string, nullable — The name of the primary contact person for the shipment at the address. <br /><br />***Note:** Either the **Contact Name** or **Company Name** must be provided.*
      - `CompanyName` string, nullable — The name of the company associated with the shipment at the address.<br /><br />***Note:** Either the **Contact Name** or **Company Name** must be provided.*
      - `ContactEmail` string, email, nullable — The email address of the contact person for any communication regarding the shipment at the address.
      - `ContactPhone` string, nullable — The contact phone number associated with the shipping location, facilitating communication regarding shipments or deliveries. <br /> <br />***Note:** Characters like +, /, -, or space are supported.*
      - `Line1` string, nullable — The first line of the address, typically containing the primary address information such as house number and street name. <br /><br />***Note:** This information is required if the address is not used from the stored addresses in the **Address Book**.*
      - `Line2` string, nullable — An optional second line for the address, often used for additional details like apartment numbers or suite designations.
      - `Line3` string, nullable — A third optional line in the address to include any further address specifications, allowing for more detailed address information if necessary.
      - `Town` string, nullable — The town or city, indicating the specific locality where the address is situated. <br /><br />***Note:** This information is required if the address is not used from the stored addresses in the **Address Book**.*
      - `Postcode` string, nullable — The postal or ZIP code corresponding to the shipping location, used for mail sorting and to identify specific geographic areas. <br /><br />***Note:** This information is required for the addresses in the UK and for some outside it. To check for the postcode requirements, refer to the **Countries** API.*
      - `County` string, nullable — The county, state, or province in which the shipping location resides, providing additional geographical context for the address.<br /><br />***Note:** This information may be required depending on the country. If the country is USA, Australia, or Canada, then it must be a valid state code or name, respectively. To check for the county/state/province requirements, refer to the **Countries** API.*
      - `CountryCode` string, nullable — An abbreviation representing the country of the shipping location, typically following the ISO 3166-1 alpha-2 standard, for example, "GB" for the United Kingdom. <br /> <br />***Note:** This information is required if the address is not used from the stored addresses in the **Address Book**.*
      - `What3Words` string, nullable — A three-word location identifier provided by the What3words service, offering a precise way to define locations using a unique combination of three words, for example, the front door of 10 Downing Street in London is identified by slurs.this.shark.
  - `Destination` Destination, required — An object providing details on the shipment destination, such as receiver and contact details.
    - `EoriNumber` string, nullable — The EORI (Economic Operators Registration and Identification) number for the receiver, which must start with the ISO Alpha-2 Country Code followed by up to 15 alphanumeric characters. For Northern Ireland, it starts with XI. <br /> <br />***Note:** This field is mandatory for B2B shipments from GB to Northern Ireland or if the receiver is a business. Make sure to provide this information here—not in the **Customs** object.*
    - `VatNumber` string, nullable — The VAT (Value Added Tax) number for the receiver, which, if applicable, is used for tax compliance. <br /> <br />***Note:** This field is mandatory if the receiver is a business. Make sure to provide this information here—not in the **Customs** object.*
    - `Address` DestinationAddress, required — The complete address of the receiver's location, consisting of multiple components including street information, locality, and so on.
      - `AddressId` string, nullable — A unique identifier for the address. This information ensures that each address can be distinctly referenced and managed within the system. <br /> <br />***Note:** If this information is provided, then all the fields under the **Address** object are ignored and the stored address in the **Address Book** will be used.*
      - `ContactName` string, nullable — The name of the primary contact person for the shipment at the address. <br /><br />***Note:** Either the **Contact Name** or **Company Name** must be provided.*
      - `CompanyName` string, nullable — The name of the company associated with the shipment at the address.<br /><br />***Note:** Either the **Contact Name** or **Company Name** must be provided.*
      - `ContactEmail` string, email, nullable — The email address of the contact person for any communication regarding the shipment at the address.
      - `ContactPhone` string, nullable — The contact phone number associated with the receiver, facilitating communication regarding shipments or deliveries. <br /> <br />***Note:** Characters like +, /, -, or space are supported.*
      - `Line1` string, nullable — The first line of the address, typically containing the primary address information such as house number and street name. <br/> <br/> ***Note:** Characters like +, /, -, or space are supported.*
      - `Line2` string, nullable — An optional second line for the address, often used for additional details like apartment numbers or suite designations.
      - `Line3` string, nullable — A third optional line in the address to include any further address specifications, allowing for more detailed address information if necessary.
      - `Town` string, nullable — The town or city, indicating the specific locality where the shipping location is situated. <br/> <br/> ***Note:** This information is required if the address is not used from the stored addresses in the **Address Book**.*
      - `Postcode` string, nullable — The postal or ZIP code corresponding to the shipping location, used for mail sorting and to identify specific geographic areas.<br/> <br/> ***Note:** This information is only required for the addresses in the UK and for some outside it. To check for the postcode requirements, refer to the **Countries** API.*
      - `County` string, nullable — The county, state, or province in which the shipping location resides, providing additional geographical context for the address.<br/> <br/> ***Note:** This information may be required depending on the country. If the country is USA, Australia, or Canada, then it must be a valid state code or name, respectively. To check for the county/state/province requirements, refer to the **Countries** API.*
      - `CountryCode` string, nullable — An abbreviation representing the country of the shipping location, following the ISO 3166-1 alpha-2 standard, for example, "GB" for the United Kingdom. <br /> <br />***Note**: This information is only required if the address is not used from the stored addresses in the **Address Book***
      - `What3Words` string, nullable — A three-word location identifier provided by the What3words service, offering a precise way to define locations using a unique combination of three words, for example, the front door of 10 Downing Street in London is identified by slurs.this.shark.
  - `CarrierSpecifics` RoyalMailShipmentRequestCarrierSpecifics — Royal Mail-specific features that can be used when creating a Royal Mail shipment.
    - `ServiceLevel` string, nullable — This field indicates the Royal Mail service level associated with the service specified in the ServiceCode field. Valid values range from 01 to 99. This parameter helps define the expected delivery speed and service quality for the shipment. <br /> <br />***Note:** If not provided, then by default, this field is set to the lowest service level for the specified service.*
    - `EbayVtn` string, nullable — The EbayVtn (eBay Virtual Tracking Number) is a field that should be provided for all shipments related to orders created on eBay. This number is essential for ensuring that tracking data for the shipment is properly integrated and made available on the eBay platform. Providing the eBay Virtual Tracking Number helps maintain visibility and communication with buyers regarding their orders.
    - `AdditionalHandlingFeesPaid` boolean, nullable — Indicates whether additional handling fees have been prepaid by the sender. <br /> <br />Valid values are the following: <br /><ul><li> **True** - fees prepaid </li><li> **False** - fees not paid and must be paid by the recipient </li></ul> <br /> <br />***Note:** By default, this field is set to false. If set to true, the value may be included in the carrier's pre-advice data, if applicable.*
    - `ServiceEnhancements` RoyalMailServiceEnhancement[], nullable — An array of objects that allows shippers to specify any additional service enhancements they would like to apply to the requested shipping service, offering flexibility in how the shipment is handled based on specific requirements or preferences. <br /> <br />***Note:** A maximum of 4 service enhancements can be used per shipment.*
      - `Code` 'CL1' | 'CL2' | 'CL3' | 'CL4' | 'CL5' | 'Signed' | 'SMS' | 'Email' | 'Safeplace' | 'LocalCollect' | 'CustomsEmail' | 'CustomsPhone', required — Enhancement code of the service enhancement. Valid values are: <br />**CL1** - Consequential Loss £1000 <br />**CL2** - Consequential Loss £2500 <br />**CL3** - Consequential Loss £5000 <br />**CL4** - Consequential Loss £7500 <br />**CL5** - Consequential Loss £10000 (Only 1 type of Consequential Loss is allowed) <br />**Signed** - a signature is required on delivery of the shipment. Can be used with 24, 48, 1st Class and 2nd Class services. <br />**SMS** - delivery updates will be sent via SMS. Can be used with Special Delivery Guaranteed, Tracked and Tracked High Volume services. <br />**Email** - delivery updates will be sent via email. Can be used with Special Delivery Guaranteed, Tracked and Tracked High Volume, International Tracked and International Tracked and Signed services. <br />**Safeplace** - the shipment will be left in a specified safeplace location. The location must be provided in the SafeplaceLocation field. Can be used with Tracked, Tracked High Volume and 24/48 services. <br />**LocalCollect** - the shipment will be delivered to a Post Office for collection by the receiver. Can be used with Special Delivery Guaranteed, Tracked and Tracked High Volume services. <br />**CustomsEmail** - Receiver email address will be used in eCustoms data. Can be used with International services. <br />**CustomsPhone** - Receiver phone number will be used in eCustoms data. Can be used with International services.
      - `SafeplaceLocation` string, nullable — Specifies the safe place where the shipment should be delivered. This location must be clearly defined to ensure proper handling and delivery according to the customer's instructions. <br /> <br />***Note:** This information is required if the Safeplace enhancement code has been selected.*
    - `OfflineBarcode` RoyalMailOfflineBarcode — Used to create a shipment record for a shipment that had a tracking number allocated outside of the SAPIENT system. This feature is only available if it has been activated on your customer account in the GUI. <br /> <br />***Note:** If the OfflineBarcode information is provided, then Process is the only valid action accepted in the Action field.* <br /> <br />**'OfflineBarcode' has been deprecated and it is recommended to use 'OfflineBarcodes' instead.**
      - `PackageOccurrence` integer, nullable — A unique identifier that is used to assign barcodes to individual packages within a shipment, ensuring accurate tracking and record-keeping for each package in the shipment.
      - `TrackingNumber` string, nullable — The tracking number to be used for the shipment. This number is mandatory for all services that require a 1D barcode. It is useful for tracking the shipment throughout its transit.
      - `UniqueId` string, required — A unique identifier that is used for tracking packages in the Royal Mail system. <br /> <br />***Note:** For offline barcode customers, only a 21-character unique identifier starting with '2B' should be provided. Proper formatting of the UniqueId information is vital to avoid processing errors during shipment requests.*
    - `OfflineBarcodes` RoyalMailOfflineBarcode[], nullable — Used to create shipment records for shipments that had a tracking number allocated outside of SAPIENT. This feature is available only if it has been activated on a customer's account in the GUI. <br /> <br />***Note:** If the OfflineBarcodes information is provided, then Process is the only valid action accepted in the Action field.*
      - `PackageOccurrence` integer, nullable — A unique identifier that is used to assign barcodes to individual packages within a shipment, ensuring accurate tracking and record-keeping for each package in the shipment.
      - `TrackingNumber` string, nullable — The tracking number to be used for the shipment. This number is mandatory for all services that require a 1D barcode. It is useful for tracking the shipment throughout its transit.
      - `UniqueId` string, required — A unique identifier that is used for tracking packages in the Royal Mail system. <br /> <br />***Note:** For offline barcode customers, only a 21-character unique identifier starting with '2B' should be provided. Proper formatting of the UniqueId information is vital to avoid processing errors during shipment requests.*
    - `PreAllocatedTrackingNumber` string, nullable — A tracking number that has been pre-allocated for a shipment. For this number to be valid, data in this Create Shipment request, such as the Shipping Account, Shipping Location, Service Code, Destination Country and Postcode (where required for the country of destination) must match the with the information provided when the pre-allocated barcode was requested.
    - `TermsOfDelivery` string, nullable — Can only be populated if the value in the Incoterms field is DDP. <br />When the shipment Incoterm is DDP, this field can be used to specify an additional Delivery Term that will be applied to the shipment. <br />Accepted values: DTP, blank.
    - `Importer` RoyalMailImporter — This object provides specifics about the importer of record for a shipment, especially when the importer of record is not the same as the receiver. This object can include essential information such as the importer's name, address, EORI number, and VAT number, which are necessary for customs processing. <br /> <br />***Note:** For certain commercial shipments with DDP incoterms, even if the receiver and the importer are the same, this object is required.*
      - `Address` ShipmentAddress, required — Address
        - `AddressId` string, nullable — A unique identifier for the address. This information ensures that each address can be distinctly referenced and managed within the system. <br /> <br />***Note:** If this information is provided, then all the fields under the **Address** object are ignored and the stored address in the **Address Book** will be used.*
        - `PudoId` string, nullable — A unique identifier for a PUDO location. This ID is retrieved from the **LocationId** field of the **Get PUDO Locations** endpoint response and is essential for identifying the specific collection point for a Royal Mail shipment. <br /> <br />***Note:** Before providing the **PudoId**, keep in mind the following:* <br /><ul><li> *The **PudoId** is only applicable for destination addresses when the shipment is being created as a collection shipment. Royal Mail does not utilise this ID for drop-off shipments.*</li><li> *The destination contact name must be provided with either its contact email or phone number.*</li><li> *The **LocalCollect** supplement code is not required - the system will automatically assign the relevant supplement codes based on the PudoId.*</li></ul>
        - `ContactName` string, nullable — The name of the primary contact person for the shipment at the address. <br /><br />***Note:** Either the **Contact Name** or **Company Name** must be provided.*
        - `CompanyName` string, nullable — The name of the company associated with the shipment at the address.<br /><br />***Note:** Either the **Contact Name** or **Company Name** must be provided.*
        - `ContactEmail` string, email, nullable — The email address of the contact person for any communication regarding the shipment at the address.
        - `ContactPhone` string, tel, nullable — Phone number.
        - `Line1` string, nullable — The first line of the address, typically containing the primary address information such as house number and street name. <br/> <br/> ***Note:** Characters like +, /, -, or space are supported.*
        - `Line2` string, nullable — An optional second line for the address, often used for additional details like apartment numbers or suite designations.
        - `Line3` string, nullable — A third optional line in the address to include any further address specifications, allowing for more detailed address information if necessary.
        - `Town` string, nullable — The town or city, indicating the specific locality where the shipping location is situated. <br/> <br/> ***Note:** This information is required if the address is not used from the stored addresses in the **Address Book**.*
        - `Postcode` string, nullable — The postal or ZIP code corresponding to the shipping location, used for mail sorting and to identify specific geographic areas.<br/> <br/> ***Note:** This information is only required for the addresses in the UK and for some outside it. To check for the postcode requirements, refer to the **Countries** API.*
        - `County` string, nullable — The county, state, or province in which the shipping location resides, providing additional geographical context for the address.<br/> <br/> ***Note:** This information may be required depending on the country. If the country is USA, Australia, or Canada, then it must be a valid state code or name, respectively. To check for the county/state/province requirements, refer to the **Countries** API.*
        - `CountryCode` string, nullable — An abbreviation representing the country of the shipping location, following the ISO 3166-1 alpha-2 standard, for example, "GB" for the United Kingdom. <br /> <br />***Note**: This information is only required if the address is not used from the stored addresses in the **Address Book***
        - `What3Words` string, nullable — A three-word location identifier provided by the What3words service, offering a precise way to define locations using a unique combination of three words, for example, the front door of 10 Downing Street in London is identified by slurs.this.shark.
      - `EoriNumber` string, nullable — Importer of Record's Economic Operators and Registration Identification (EORI) number. <br />Importer EORI number starts with the ISO Alpha-2 Country Code followed by a maximum 15 alphanumeric characters. For Northern Ireland, EORI numbers start with XI.
      - `VatNumber` string, nullable — Importer of Record's Value Added Tax (VAT) number.
    - `EnhancedCustomsInformation` RoyalMailEnhancedCustomsInformation[], nullable — Used to provide additional customs data for an item SKU code that is also provided in the Items object, when the enhanced data is applicable to the item being shipped.
      - `SkuCode` string, nullable — The SKU code of the item the enhanced customs information is being provided for. <br />The SKU code provided here must also be provided in the Items object, in order to associate the enhanced customs information with the standard item information for the item. <br />Mandatory if any enhancedCustomsInformation fields are populated.
      - `LicenseNumber` string, nullable — Sender's License Number for the item specified in the skuCode field, when applicable to the item being shipped. E.g. Health certificate or controlled goods.
      - `CertificateNumber` string, nullable — Sender's Certificate Number for the item specified in the skuCode field, when applicable to the item being shipped. E.g. Health certificate or controlled goods.
      - `OriginPreferenceCode` integer, nullable — Can be used to indicate the item is eligible for a preferential duty rate. <br />Accepted values: <br />300 – Preferential treatment is applied to the item. <br />100 or blank – Preferential treatment is not applied to the item.
  - `Packages` RoyalMailPackage[], required — Used to provide information on the packages that are being sent in this shipment.<br /> <br />***Note:** You must add at least one package to the shipment.*
    - `PackageOccurrence` integer, nullable — A unique identifier for each package within the shipment that is used to match a returned package ID to this package. This field can also be used to assign items to a specific package. <br /> <br />***Note:** For Royal Mail dutiable multi-package shipments that are not using a consignment service, items must be assigned to a package so that accurate customs information is given. Therefore, if the shipment contains more than one package, and it is not using a consignment service, then the **PackageOccurrence** is required.*
    - `PackageType` 'Letter' | 'LargeLetter' | 'Parcel' | 'PrintedPapers' — Defines the type of package being shipped (for example, tube, pallet, and so on). This helps Royal Mail categorise and handle the package appropriately during transit. <br /> <br />***Note:** By default, this field is set to the largest package type for the requested service.*
    - `DeclaredWeight` number, double, nullable — The total weight of the package being declared in the unit of measure specified in the **WeightUnitOfMeasure** field. <br /> <br />***Note:** The minimum allowed weight is 0.001 kg and the maximum weight is dependent on the carrier, service and destination. This field is mandatory for shipments using non-consignment services.*
    - `DeclaredValue` number, double, nullable — The declared monetary value of the package specified in the **CurrencyCode** field. <br /> <br />***Note:** If provided, then the declared value must meet or exceed the sum of all item values assigned to this package. Otherwise, it defaults to this sum. This value can be used for non-consignment services, though it is not mandatory.*
    - `Dimensions` Dimensions — Used to provide the maximum allowable dimensions for packages. It specifies the limits that must not be exceeded for packages to be eligible for the shipping service and package type. <br /> <br />***Note:** The Dimensions object in the request is optional, but if it is provided, then all of the fields in the object (width, length, and height) must be populated. The maximum dimensions accepted are dependent on the service and the package type.*
      - `Length` number, double, required — The length of the shipment package in the unit of measure specified in the **UnitOfMeasure** field. <br /> <br />***Note:** The maximum accepted length is dependent on the service and package type.*
      - `Width` number, double, required — The width of the shipment package in the unit of measure specified in the **UnitOfMeasure** field. <br /> <br />***Note:** The maximum accepted width is dependent on the service and package type.*
      - `Height` number, double, required — The height of the shipment package in the unit of measure specified in the **UnitOfMeasure** field. <br /> <br />***Note:** The maximum accepted height is dependent on the service and package type.*
  - `Items` Item[], nullable — Used to provide information on the individual goods/products being shipped within the package. This includes vital details, such as SKU code for inventory tracking, quantity of each item, description for clarity, and shipping specifics like weight, customs classifications (HS Code), and country of origin. <br /> <br />***Note:** The item information is only required for dutiable shipments. Non-Dutiable and Documents Only (DOX) shipments do not require item information. Please be advised that the item verification on a shipment is done via Hurricane services; therefore, it should be enabled. The maximum number of distinct items that will be verified in a single shipment is 15.*
    - `SkuCode` string, nullable — A unique Stock Keeping Unit (SKU) code assigned to the item. This code is used for tracking inventory, helping users identify specific items easily.
    - `PackageOccurrence` integer, nullable — A unique identifier for each package within the shipment that is used to assign items to a specific package. <br /> <br />***Note:** The package occurence provided here must exist on one of the packages in the **Packages** object. If multiple packages exist and a consignment service is not used, this field is mandatory to ensure each package occurrence is distinct.*
    - `Quantity` integer, required — The quantity of this item in the package being shipped.
    - `Description` string, nullable — A brief summary providing details about the specifc item being shipped, outlining its type, features, uses, and any pertinent information that helps users understand the item, such as 'skirt' instead of 'ladies clothing.' <br /> <br />***Note:** This information is mandatory for dutiable shipments unless a SKU Code of a stored product is provided.If a SKU Code of a stored product is present and this field is left blank, it will be automatically populated from the stored product; if both are provided, the input in this field takes precedence.*
    - `Value` number, double, nullable — The monetary value of a single instance of the item, in the currency specified in the **CurrencyCode** field. <br /> <br />***Note:** This information is mandatory for dutiable shipments unless a SKU Code of a stored product is provided.If a SKU Code of a stored product is present and this field is left blank, it will be automatically populated from the stored product; if both are provided, the input in this field takes precedence.*
    - `Weight` number, double, nullable — The weight of a single instance of the item, in the unit of measure specified in the **WeightUnitOfMeasure** field. This is required for dutiable shipments unless a SKU Code from the stored product is used. If the SKU Code is available and the weight is left blank, it will be populated from the stored product; otherwise, the provided weight will be used. <br /> <br />***Note:** The maximum allowed weight is 1000 KG.For non-dutiable shipments, a weight of 0 is accepted.For dutiable shipments, an item weight of 1 gram or greater must be provided.*
    - `ImageURL` string, uri, nullable — This field provides the URL of the product image with the shipment details. This helps customers visually identify the product when selecting items for return in the Returns system.
    - `HSCode` string, nullable — The Harmonized System (HS) code used by customs to determine potential duties and taxes for the product. This code ranges from 6 to 13 alphanumeric characters, depending on specific services or destinations. Some countries may also use the HS codes of other character lengths. <br /> <br />***Note:** Characters like space and dot are supported.* <br /> <br />For more information on HS Codes and to find the correct HS Codes for your items, refer to the following link: https://www.gov.uk/trade-tariff
    - `CountryOfOrigin` string, nullable — An abbreviation representing the country where the item was manufactured or produced, following the ISO 3166-1 alpha-2 standard, for example, "GB" for the United Kingdom. This information is important for customs declarations and compliance with import/export regulations. <br /> <br />***Note:** Depending on the carrier and destination country, this information may be required for dutiable shipments.*
    - `ManufactureProductId` string, nullable — A unique manufacturer identifier for the item being shipped, for example, proprietary manufacturer code, model number, or internal code. This field is used to reference the shipped item and supports carrier-specific requirements.
    - `StandardisedProductId` string, nullable — A globally recognised product identifier for the item being shipped, for example, GTIN, EAN, and UPC. This field is used for standardised item identification and supports carrier-specific requirements for customs and risk assessment.
    - `SupplementaryUnits` number, double, nullable — This field specifies any additional unit of measurements that supplement the primary unit of measurements for the item being shipped. <br />For example: The HS code for PVC Black Flooring Roll 2.5mm is 391890. HMRC/Tariff determines that you provide a supplementary unit in square metres (MTK) with HS code 391890. <br /> <br />***Note:** For B2B shipments to Northern Ireland, this field is optional if the HMRC/Tariff determines that the Tariff/Harmonisation Code provided requires a supplementary unit.* <br />*You can enter values to a maximum of 6 decimal places.*
  - `Customs` Customs — Used to provide information for customs clearance related to the shipment. This includes, reasons for export, applicable incoterms, any pre-registration numbers and type required, shipping and other charges, as well as details about the invoice and whether an export licence is needed. It ensures compliance with international shipping regulations.
    - `ReasonForExport` string, nullable — Identifies the purpose of the export, such as sale, gift, or return. This information is useful for customs processing to determine the appropriate tariffs and requirements.<br>This field is mandatory for Yodel international shipments.</br>The following values are accepted:</br><ul><li>Sales</li><li>Gift</li><li>Sample</li><li>Personal</li></ul>
    - `Incoterms` 'DDU' | 'DDP' | 'DAP' | 'DAT' — Specifies the International Commercial Terms (Incoterms) applicable to the shipment, governing responsibilities and financial obligations. <br /> <br />Valid values include the following: <br /><ul><li>**DDU** — Delivered Duty Unpaid. The receiver is responsible for paying customs duties and taxes.</li><li>**DDP** — Delivered Duty Paid. The seller is responsible for paying customs duties and taxes.</li><li>**DAP** — Delivered At Place. The receiver is responsible for paying customs duties and taxes.</li><li>**DAT** — Delivered At Terminal. The receiver is responsible for paying customs duties and taxes.</li></ul> <br />***Note:** By default, this field is set to DDU if not provided for dutiable shipments. Please be advised that this information is not required for non-dutiable shipments.*
    - `PreRegistrationNumber` string, nullable — A number for tax pre-registration in countries where required for compliance during DDU shipments.<br /> <br />If applicable, this number is required for countries operating a Tax Pre-Registration scheme (for example, VOEC in Norway, GST in Australia) when shipping under DDU Incoterms. If not provided and DDU is specified, any pre-registration numbers configured in the Customs Settings GUI for the account will be used. <br /> <br />***Note:** VAT and EORI numbers should be provided in the Shipper and receiver **VatNumber** and **EoriNumber** fields, not in this field.*
    - `PreRegistrationType` string, nullable — The type of pre-registration number provided in the **PreRegistrationNumber** element, specifying the registration scheme type. This field is mandatory if a **PreRegistrationNumber** is provided. Otherwise, it is ignored. <br /> <br />***Note:** VAT and EORI numbers should be provided in the Shipper and receiver **VatNumber** and **EoriNumber** fields, not in this field.*
    - `ShippingCharges` number, double, nullable — The postage amount paid by the customer for the international shipments, which can be 0.00 if free delivery is offered. This amount is used for calculating customs fees and should be in the currency specified in the **ShipmentInformation** > **Currency** field.
    - `OtherCharges` number, double, nullable — The additional costs charged to the customer beyond standard shipping, such as insurance fees. This field can be left blank or set to 0.00 if no additional charges apply. Values should be in the currency specified in the **ShipmentInformation** > **Currency** field.
    - `QuotedLandedCost` number, double, nullable — The total cost quoted to the customer when the shipment reaches the destination, including duties and taxes, and must be expressed in the currency specified in the **ShipmentInformation** > **Currency** field. <br /> <br />***Note:** This information is required for some international destinations when the shipment incoterms are DDP.*
    - `InvoiceNumber` string, nullable — A specific number that is associated with a shipment. This is useful for tracking, billing, and reconciliation purposes. <br /> <br />***Note:** When sending an item to an overseas address and a Commercial or Proforma invoice is available, the **InvoiceNumber** and **InvoiceDate** should be provided to support customs processing.If provided, it will be displayed on commercial invoices generated for the shipment. Please be advised that this field is required if the **InvoiceDate** is provided.*
    - `InvoiceDate` string, date, nullable — The date on which the invoice was created. This information is useful for record-keeping, billing cycles, and tracking payment due dates. <br /> <br />***Note:** The **InvoiceDate** must be in the YYYY-MM-DD format. This field is ignored if the **InvoiceNumber** is not provided. If the **InvoiceNumber** is provided without the invoice date, then the **InvoiceDate** defaults to today's date.*
    - `ExportLicenceRequired` boolean, nullable — A boolean flag indicating whether an export licence is needed for the shipment, particularly for goods predominantly used for military purposes. If required, the export licence should be affixed to the outside of the package. <br /> <br />***Note:** To learn more about the types of items requiring an export licence, refer to the UK Government website.*
    - `Airn` string, nullable — The AIRN (Address Identification Reference Number) is the generic name given to a national identification number for the overseas recipient of an item. This is required by certain countries for customs clearance. <br /> <br />***Note:** If the AIRN is available, then it should be provided for items being exported to countries where the customs/tax authority requests one, such as Russia and Brazil.*
  - `ReturnToSender` ReturnToSender — Used to provide the address details to be used when returning the shipment back to the sender. <br /> <br />***Note:** If this information is not provided, then the shipping location's address is used.*
    - `Address` ReturnToSenderAddress — The complete address of the return to sender location, consisting of multiple components including street information, locality, and so on.
      - `AddressId` string, nullable — A unique identifier for the address. This information ensures that each address can be distinctly referenced and managed within the system. <br /> <br />***Note:** If this information is provided, then all the fields under the **Address** object are ignored and the stored address in the **Address Book** will be used.*
      - `ContactName` string, nullable — The name of the primary contact person for the shipment at the address. <br /><br />***Note:** Either the **Contact Name** or **Company Name** must be provided.*
      - `CompanyName` string, nullable — The name of the company associated with the shipment at the address.<br /><br />***Note:** Either the **Contact Name** or **Company Name** must be provided.*
      - `ContactEmail` string, email, nullable — The email address of the contact person for any communication regarding the shipment at the address.
      - `ContactPhone` string, nullable — The contact phone number associated with the return to sender address, facilitating communication regarding shipments or deliveries. <br /> <br />***Note:** Characters like +, /, -, or space are supported.*
      - `Line1` string, nullable — The first line of the address, typically containing the primary address information such as house number and street name. <br/> <br/> ***Note:** Characters like +, /, -, or space are supported.*
      - `Line2` string, nullable — An optional second line for the address, often used for additional details like apartment numbers or suite designations.
      - `Line3` string, nullable — A third optional line in the address to include any further address specifications, allowing for more detailed address information if necessary.
      - `Town` string, nullable — The town or city, indicating the specific locality where the shipping location is situated. <br/> <br/> ***Note:** This information is required if the address is not used from the stored addresses in the **Address Book**.*
      - `Postcode` string, nullable — The postal or ZIP code corresponding to the shipping location, used for mail sorting and to identify specific geographic areas.<br/> <br/> ***Note:** This information is only required for the addresses in the UK and for some outside it. To check for the postcode requirements, refer to the **Countries** API.*
      - `County` string, nullable — The county, state, or province in which the shipping location resides, providing additional geographical context for the address.<br/> <br/> ***Note:** This information may be required depending on the country. If the country is USA, Australia, or Canada, then it must be a valid state code or name, respectively. To check for the county/state/province requirements, refer to the **Countries** API.*
      - `CountryCode` string, nullable — An abbreviation representing the country of the shipping location, following the ISO 3166-1 alpha-2 standard, for example, "GB" for the United Kingdom. <br /> <br />***Note**: This information is only required if the address is not used from the stored addresses in the **Address Book***
      - `What3Words` string, nullable — A three-word location identifier provided by the What3words service, offering a precise way to define locations using a unique combination of three words, for example, the front door of 10 Downing Street in London is identified by slurs.this.shark.

## Response `200`

The shipment was created successfully.

- RoyalMailLabelFormatRoyalMailShipmentResponseCarrierSpecificsPackageResponseCreateShipmentResponse — Create Shipment Response
  - `ConsignmentShipmentId` string, 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.*
  - `ConsignmentTrackingNumber` string, 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.*
  - `ConsignmentCarrierTrackingUrl` string, 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.*
  - `Labels` string, 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>
  - `Packages` RoyalMailShipmentResponseCarrierSpecificsPackageResponse[], nullable — An array that details information about each package included in the shipment. This includes essential data, such as package occurrence and tracking information. Each package is clearly documented to facilitate tracking and handling.
    - `PackageOccurrence` integer — Identifies the sequential number or occurrence of the package provided in the request for the shipment. It allows for easy differentiation of multiple packages and helps manage inventory or logistics operations related to the shipment.
    - `TrackingNumber` string, nullable — The specific tracking number assigned to the package occurrence by the carrier. This number can be used to track the package's status and location during its transit.
    - `CarrierTrackingUrl` string, uri, nullable — A unique URL provided for each package that allows shippers and recipients to track the specific package directly on the carrier's website. This link leads to a dedicated tracking page where detailed updates can be accessed. <br /> <br />***Note:** This field is only populated, if this feature is available.*
    - `Label` string, nullable — This field provides the Base64-encoded label for each package in the shipment only if the **ReturnLabelsAtPackageLevel** field is set to True. If **ReturnLabelsAtPackageLevel** is not specified, or is set to False, then this field will not be returned, and instead, the main body of the Create Shipment response will include the label data.
    - `CarrierDetails` RoyalMailShipmentResponseCarrierSpecifics — Used to provide the response related to the carrier's processing and tracking of the shipment. This object serves for managing the shipment and generating relevant tracking and label information.
      - `UniqueId` string, required — A unique identifier assigned by Royal Mail to uniquely identify the shipment. This ID is critical for tracking and referencing the shipment within the Royal Mail system.
      - `PartnerDetails` RoyalMailPartnerDetails — Details of the partner label created.
        - `PartnerName` string, nullable — The name of the partner where partners carrier used to deliver the shipment, if applicable.
        - `PartnerCode` string, nullable — The code of the partner carrier used to deliver the shipment is applicable.
        - `PartnerTrackingNumber` string, nullable — The partner carrier tracking number for this package occurrence. <br />Can be used with the partner tracking URL to track the shipment on the partner carrier's website.
        - `PartnerTrackingUrl` string, nullable — The URL of the partner carrier's tracking webpage. <br /> Can be used with the partner tracking number to track the shipment on the partner carrier's website.
      - `DataStreamDetails` RoyalMailDataStreamDetails — Provides all the information required to create a custom label for the shipment. This object is only present if the **DATASTREAM** label format was specified in the request, providing the necessary components to generate the label within your own system.
        - `Primary2DBarcodeImage` string, required — A base64 encoded PNG image of the 2D data matrix barcode associated with the shipment.
        - `Primary2DBarcodeData` string, required — The actual data encoded in the primary 2D barcode, also in base64 encoded format. This data is required to create the 2D data matrix barcode and should be decoded before use.
        - `FormattedUniqueId` string, required — A label associated with the 2D data matrix barcode. It serves as a reference to the unique identifier assigned to the shipment.
        - `GazetteerCodes` RoyalMailGazetteerCodes — Gazetteer Codes
          - `Part1` string, required — Represents the first part of the gazetteer code which is the outward part of the postcode. This code is crucial for routing shipments to a broader geographical region before it it sorted to specific delivery points.
          - `Part2` string, required — Represents the second part of the inward gazetteer code in a post code. It provides additional specificity for the delivery location and is used together with the outward code to pinpoint exact addresses.
          - `Part3` string, nullable — Represents additional components of the inward code to provide further details, enhancing accuracy of shipment delivery.
          - `Part4` string, nullable — Represents additional components of the inward code to provide further details, enhancing accuracy of shipment delivery. <br /> <br />***Note**: Please be advised that either the **Part4** gazetteer code or **SecondaryRoutingCode**, or neither, will be returned in the response.*
        - `SecondaryRoutingCode` string, nullable — Represents the secondary routing code that can be used to refine the addressing of shipments to the correct depot. <br /> <br />***Note**: Please be advised that either the **SecondaryRoutingCode** or the **Part4** gazetteer code, or neither, will be returned in the response.*
        - `Primary1DBarcodeImage` string, nullable — A base64 encoded PNG image of a 1D barcode, provided only if the service requires the barcode to be displayed on the label. This image represents the tracking information in a format that can be scanned.
        - `Primary1DBarcodeData` string, nullable — The data necessary to create the 1D barcode associated with the shipment, provided only if the service requires the barcode to be displayed on the label.
        - `HighVolumeBarcodeImage` string, nullable — A base64 encoded PNG image of the barcode intended for use with high-volume tracking services. This field is populated only when the service (Tracked High Volume) requires having a barcode on the label.
        - `HighVolumeBarcodeData` string, nullable — The data required to create the corresponding barcode for the high-volume service. This field is populated only when the service (Tracked High Volume) requires having a barcode on the label.
    - `ShipmentId` string, uuid, nullable — A unique identifier associated with the specific shipment containing the package. This ID is crucial for linking the package to its overall shipment, aiding in organisation and tracking. <br /> <br />***Note:** This field is only populated if the service is a non-consignment service.*
  - `Documents` string, 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.

## Other responses

- `400` — Invalid request response.
- `401` — Unauthorized
- `403` — Forbidden
- `404` — The carrier was not found.
- `500` — Internal Server Error

---

[API](https://skmtc.dev/intersoftsapient/apis/sapient-core-api.md) · [All operations](https://skmtc.dev/intersoftsapient/apis/sapient-core-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/intersoftsapient/sapient-core-api/revisions/3315ad0b5875/schema)