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

# Create Shipment Async

`POST /v4/shipments/async/rm`

## Request

- Base URL: `https://api.intersoftsapient.net`
- URL: `https://api.intersoftsapient.net/v4/shipments/async/rm`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://authentication.intersoftsapient.net/connect/token`

Create a shipment request for asynchronous processing. Unlike the standard Create Shipment endpoint, this endpoint performs only initial validation on the shipment data and does not return a label in the response.
<br /> 
<br />If the request passes validation and a Shipments Webhook is configured, the shipment is queued for background processing. The response from the Create Shipment request will be pushed to the webhook.
<br /> 
<br />The immediate API response contains only a **RequestId**, which can be used to track and correlate the request with subsequent webhook responses.
<br />
<br />***Note**: This endpoint must only be used when the Shipments Webhook is configured within the SAPIENT UI.*

## 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.*<br>*Please be advised that if the shipment is created using a consignment service (shipments with multiple packages) with a partner carrier—via the **Create** or **Allocate** actions—then the system will split the packages into multiple individual shipments without generating the consignment number.*<br><br/>*Please be advised that if the shipment is created using a consignment service (shipments with multiple packages) with a partner carrier—via the **Create** or **Allocate** actions—then the system will split the packages into multiple individual shipments without generating the consignment number.*
    - `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 /><ul><li> **B2C** - Business to Consumer </li><li> **B2B** - Business to Business </li><li> **D2C** - Direct to Consumer </li><li> **C2B** - Consumer to Business </li></ul> <br />***Note:** By default, this field is set to B2C.*<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 measurement for the weight provided, such as **TotalWeight**, indicating whether the weight is specified in kilograms (KG) or grams (G), ensuring clarity for shipping calculations. <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.<br><br/>***Note:** If this number is provided for the Royal Mail shipment, make sure that this number already exists for the department that has been set up with Royal Mail, and must be exactly 10 characters in length.*
    - `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.*
      - `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.<br /><br />***Note**: Either the **Contact Email** or **Contact Phone** must be provided for shipments destined for the United States and US territories.*
      - `ContactPhone` string, nullable: The contact phone number associated with the shipping location, facilitating communication regarding shipments or deliveries.<br /><br />***Note**: Either the **Contact Email** or **Contact Phone** must be provided for shipments destined for the United States and US territories. 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 array of objects 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:** 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:** 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.*
      - `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, 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: This field is used to specify an additional delivery term that will be applied to the shipment. In this case, the recipient remains the importer and is responsible for the accuracy of the import declaration and any risk. <br /> <br />***Note:** Populate this field only when the Incoterms field is set to DDP.*
    - `Importer` RoyalMailImporter: The complete address of the importer's location, consisting of multiple components including street information, locality, and so on.
      - `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: The EORI (Economic Operators Registration and Identification) number for the importer of record, which must start with the ISO Alpha-2 Country Code followed by up to 15 alphanumeric characters. For Northern Ireland, it starts with XI.
      - `VatNumber` string, nullable: The VAT (Value Added Tax) number for the importer of record, which is required for business transactions, helping to ensure compliance with tax regulations.
    - `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: A unique Stock Keeping Unit (SKU) code of the item for which the enhanced customs information is being provided. This code is used for tracking inventory, helping users identify specific items easily. <br /> <br /> ***Note:** This SKU code must also be specified in the **Items** object to link the enhanced customs information to the corresponding item. This field is required if any enhanced customs information fields are populated.*
      - `LicenseNumber` string, nullable: The sender's licence number associated with the item specified in the **SkuCode** field, where required for the shipment of regulated or controlled goods, such as goods requiring a health certificate.
      - `CertificateNumber` string, nullable: The sender's certificate number associated with the item specified in the **SkuCode** field, where required for the shipment of regulated or controlled goods, such as goods requiring a health certificate
      - `OriginPreferenceCode` integer, nullable: This field indicates whether the item is eligible for preferential duty treatment under a qualifying trade agreement. <br /> <br />Valid values are the following: <br /><ul><li>**300** - Preferential treatment is applied to the item.</li><li>**100 or blank** - Preferential treatment is not applied to the item.</li></ul>
  - `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 occurrence 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.
    - `PGAReferenceNumber` string, nullable: The Partner Government Agency (PGA) reference number associated with the item, used to support customs and regulatory requirements for shipments to the United States and US territories. <br /> <br />***Note:** This field is applicable to shipments destined for the United States and US territories.*
    - `Hazmat` Hazmat: Hazmat Information
      - `UNCode` string, nullable: The United Nations (UN) code assigned to the hazardous material, which denotes its classification for transport. This code is critical for safety and compliance during shipping.
      - `ProperShippingName` string, nullable: The official name designated for the hazardous material as required by regulations. This name is used to inform handlers of the nature of the hazard during transport.
      - `Class` string, required: The class number of the hazardous material as per UN regulations, indicating the potential risk associated with the product.
      - `Id8000Category` string, nullable: An optional designation used for certain hazardous materials classified under Class 9, providing additional regulatory requirements for handling and transport. <br /> <br />Available values are the following: <br /> <br /><ul><li>Medicines</li><li>Perfume/Aftershave</li><li>Nail Varnish</li><li>Toiletry or Medical Aerosols</li></ul> <br /> <br />When a customer submits a create shipment request, they must be aware of the following conditions: <br /> <br /><ul><li> If the **ID8000Category** field is populated and the **Class** field is set to any value other than 9, then the **ID8000Category** will be disregarded, and the information will not be saved in the shipment record.</li><li> If the **ID8000Category** field is populated and the Class field is set to 9, then the system will create the product and save the **ID8000** data to the product record.</li></ul>
      - `Quantity` number, double, nullable: The quantity of the hazardous material in the specified **UnitOfMeasure**. This information is vital for compliance with shipping regulations pertaining to hazardous materials.
      - `UnitOfMeasure` 'NONE' | 'L' | 'KG': The unit of measurement for the quantity of hazardous material, for example, litres (for liquids) or kilograms (for solids). This provides clarity regarding the amount of hazardous goods present. <br />***Note:** This field is only required if **Quantity** and **UNCode** is specified.*
      - `EmergencyActionCode` string, nullable: A code providing emergency response instructions for handling hazardous materials during transport. This code is critical for safety and risk management.
      - `HazchemNumber` string, nullable: A number that indicates the type of hazardous material and the precautions necessary for its transport. This helps in emergency situations through quick identification.
      - `SpecialistAdviceContactNumber` string, nullable: A contact number for expert advice regarding the handling and transport of hazardous materials. This information is crucial during emergencies or if unusual situations arise. <br />***Note:** If this informarion is not provided and the hazardous material is used in your Create Shipment request, then the contact number will be sent from the customer shipping account record.*
      - `PrintId8000Label` boolean, nullable: A boolean field that provides customers with the choice to generate the ID8000 label along with the shipping label. When set to true, the system returns the ID8000 labels for class 9 hazardous products contained within the shipment. By default, this field is set to false. <br /> <br />***Note:** Before populating this field, keep in mind the following: <br /><ul><li>This field is ignored if the **Action** field is populated with values other than **Process**.</li><li>The ID8000 label is returned in the PDF format only.*</li></ul>
    - `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. This field is mandatory for Royal Mail international shipments.</br>Valid values are the following:</br><ul><li>Gift</li><li>Commercial Sample</li><li>Documents</li><li>Sale of Goods</li><li>Ecommerce Sale of Goods</li><li>Commercial Sale of Goods</li><li>Return of Goods</li><li>Mixed Content</li><li>Other</li></ul></br>_**Note**_: _Before populating this field, please bear in mind the following:</br></br>_<ul><li>_If the **Sale of Goods** value is selected, the system automatically determines whether the shipment is **Ecommerce (B2C or D2C)** or **Commercial (B2B)** based on the value provided in the **BusinessTransactionType** field in the create shipment request._</li><li>_If a Royal Mail shipment uses a commercial customs service and the reason for export is set to **Gift**, the shipment will fail and an error will be returned._</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.*
      - `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, 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.

- CreateShipmentViaWebhookResponse: Create Shipment via shipment webhook Response
  - `RequestId` string, uuid: A unique identifier generated by SAPIENT for each shipment request submitted via the **Create Shipment Async** endpoint. This ID used to match the subsequent asynchronous Shipment Webhook response with the original request.

## 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/royal-mail.md) - [All operations](https://skmtc.dev/intersoftsapient/apis/royal-mail/llms.txt) - [OpenAPI document](https://skmtc.dev/intersoftsapient/apis/royal-mail/revisions/acb747a1c3b6?raw)