---
title: "ShipRequest API"
slug: "shiprequest-api"
updated: 2026-10-01T15:17:13Z
published: 2026-10-01T15:17:13Z
canonical: "mercurydocs.landmarkglobal.com/shiprequest-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://mercurydocs.landmarkglobal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ShipRequest API

The following details how to import shipment data to Mercury via an [**API request**](https://mercurydocs.landmarkglobal.com/docs/api-specifications).

#### Overview

The protocol is based on XML data exchange with HTTP used as a transport. A non-validating parser is used and hence no internal or external DTD needs to be specified. The data must be well formed and all validation is handled at the application (not parser) level. Error handling will be done by always including the <Errors> container in the response. The Errors element will not be returned if no errors are found.

#### **Connection**

To connect to the site use the following HTTPS URL via regular POST method with the parameter RQXML=<your xml document> **[https://api.landmarkglobal.com/v2/Ship.php](https://api.landmarkglobal.com/v2/Ship.php)**

#### **Encoding**

Mercury uses UTF-8 for character encoding. If your system outputs in an encoding other than UTF-8, please include an encoding flag in your XML header.

Example: <?xml version="1.0" encoding="UTF-8"?>

Example: <?xml version="1.0" encoding="ISO-8859-1"?>

#### **Test Mode**

When first given access to the API, the client will be placed in Test mode. Requests made while in test mode will not act on live data. After approval has been received to go live from Landmark, all requests are active unless the <Test> flag is passed. During a test API call, orders will not be cancelled but errors will be reported when appropriate.

During a test API call, validation will be very basic, focusing on fields being required and passing sane values. Assuming the request passes the basic validation, **responses are randomized**. Some requests will succeed and some will fail with different error messages. This is done so that the programmer has an opportunity to see a wide variety of responses and can be prepared to handle many potential results.

#### **Troubleshooting**

If you receive a </Response> error with the message "Required element login not found", then please ensure you are properly including the login nodes and credentials. Additionally, the API will return this error when it could not parse the XML.

#### ShipRequest Fields

The following table lists the required and optional fields when sending an API ShipRequest.

Child/Nested ElementsAn asterisk (*) denotes a child element that is nested inside another element. See the [example request](/v1/docs/shiprequest-api#shiprequest) in the following section.

| Field/Element | Required? | Type | Description/Notes |
| --- | --- | --- | --- |
| *Authentication/Login* |
| Username | **Yes** | String | Identifies the mercury user making the API request |
| Password | **Yes** | String | Authenticates the mercury user submitting the API request |
| *Request* |
| Test | No | Boolean | A value of "true" notes that the request is a test and the shipment will not be created in Mercury. A dummy message will be sent instead. If the field is not there or the value is "false", a real request is sent. |
| ClientID | **Yes** | String | Unique automated identifier generated by Mercury system upon creation of a new client (e.g., "1766" or "354") |
| AccountNumber | No | String | The client account that should be billed for shipping and handling this package. This field is only used by clients with multiple account numbers. See integration manager for relevant account numbers |
| Reference | **Yes** | String | Unique identifier assigned to the shipment |
| ShipTo | **Yes** | String | The consignee and address information where the shipment should be sent. Note that for return shipments, the "ShipTo" address is treated as the sender/"from" address. |
| *Name | **Yes** | String | **This is a child element of "ShipTo"* |
| *Attention | No | String | **This is a child element of "ShipTo"* |
| *Address1 | **Yes** | String | **This is a child element of "ShipTo"* |
| *Address2 | No | String | **This is a child element of "ShipTo"* |
| *Address3 | No | String | **This is a child element of "ShipTo"* |
| *City | **Yes** | String | **This is a child element of "ShipTo"* |
| *State | **Yes** | String | **This is a child element of "ShipTo"* |
| *PostalCode | **Yes** | String | **This is a child element of "ShipTo"* |
| *Country | **Yes** | String | Use ISO-3166-2 standard country abbreviation (e.g., "CA" for Canada) |
| *Phone | No | String | Optional, but encouraged |
| *Email | No | String | Optional |
| *ConsigneeTaxID | No | String | Optional; for countries that require an individual's tax id to import as DDP. |
| ShippingLane | **Yes** | String | Allows for fine-grained control over the routing of a shipment. |
| *Region | **Yes** | String | The Region field links the shipment to a Landmark facility combination and is determined on a case-by-case basis. Please contact your Integration Manager for details per shipping facility. **This is a child element of ShippingLane* |
| ShipMethod | **Yes** | String |  |
| OrderTotal | **Conditional** | Decimal | Amount paid by the customer for all the items in their order. **Required in instances where the shipment information represents a partial shipment of products comprising a larger order.** |
| OrderInsuranceFreightTotal | **Conditional** | Decimal | Amount paid by the customer for shipping their entire order. **Required in instances where the shipment information represents a partial shipment of products comprising a larger order.** |
| ShipmentInsuranceFreight | **Yes** | Decimal | Amount charged for shipping and any insurance for the shipment. This value does not include the amount charged for purchased items (i.e., Item Unit Value) |
| ItemsCurrency | **Yes** | String | Use ISO 4217 code to represent the currency (i.e. USD, CAD) |
| IsCommercialShipment | No | Boolean | Optional boolean, and only used in cases when client requires shipments to be commercially cleared (i.e. B2B clearance) |
| LabelFormat | No | String | Optional. Default is "PDF". Also supports JPG, GIF, BMP, PNG, and ZPL |
| LabelDPI | No | String | Optional. Only used for ZPL format. Specifies either 203 or 300 DPI images (default is 203 if not provided) |
| LabelEncoding | No | String | Optional. Default is "LINKS" unless the LabelFormat is ZPL. **For ZPL format, do NOT specify label encoding.** Possible values: - LINKS - Returns links to all labels which must be retrieved - BASE64 - A Base64 encoded label image is returned directly in the XML response in a <LabelImage> tag - BASE64COMPRESSED - A GZcompressed and Base64 encoded label image is returned directly in the XML response in <LabelImage> tag |
| Packages | **Yes** | (Container Element) | Element to contain information on shipment's package(s) |
| *Package | **Yes** | (Container Element) | Element to contain information about an individual package **This is a child element within "Packages"* |
| **WeightUnit | No | String | Unit of measure used for package weight. Optional. Default is LB (pounds). Supports LB, KG, G. ***This is a child element within a "Package" element* |
| **Weight | **Yes** | Decimal | Will be in pounds unless otherwise specified by WeightUnit ***This is a child element within a "Package" element* |
| **DimensionsUnit | No | String | Unit of measure used for package dimensions. Optional. Default is IN (inches). Supports IN, CM ***This is a child element within a "Package" element* |
| **Length | No | Decimal | ***This is a child element within a "Package" element* |
| **Width | No | Decimal | ***This is a child element within a "Package" element* |
| **Height | No | Decimal | ***This is a child element within a "Package" element* |
| **PackageReference | No | String | Another reference for the client. ***This is a child element within a "Package" element* |
| Items | **Conditional** | (Container Element) | Element to contain information on shipment's item(s) **Required if the shipment will be crossing a customs border.** |
| *Item | **Conditional** | (Container Element) | Element to contain information about an individual item in the shipment **Required if the shipment will be crossing a customs border.** **This is a child element within "Items"* |
| **Sku | **Conditional** | String | The item's unique sku **Required if the shipment will be crossing a customs border.** ***This is a child element within an "Item" element* |
| **DangerousGoodsInformation | **Conditional** | (Container Element) | Element to contain information on an item's dangerous goods information, if applicable **Required if the shipment contains DGs.** For more information, see [Mercury's DG system documentation](https://mercurydocs.landmarkglobal.com/docs/mercurys-dangerous-goods-system). ***This is a child element within an "Item" element* |
| ***ContainsDangerousGoods | **Conditional** | Boolean | Flag to declare that item contains {{glossary.dangerous goods}} **Required if the shipment contains {{glossary.DGs}}.** "1" = true (i.e., the item contains dangerous goods) ****This is a child element within "DangerousGoodsInformation"* |
| ***UNCode | **Conditional** | String | **Required if the shipment contains DGs. Must reference a valid DG UN code (e.g. UN3481).** For supported UN Codes, see [Mercury's DG system documentation](https://mercurydocs.landmarkglobal.com/docs/mercurys-dangerous-goods-system#supported-codes). ****This is a child element within "DangerousGoodsInformation"* |
| ***PackingGroup | **Conditional** | String | **Required for some UN Codes. Must contain a valid packing group value (i.e. "I", "II", "III").** For more information, see [Mercury's DG system documentation](https://mercurydocs.landmarkglobal.com/docs/mercurys-dangerous-goods-system#packing-groups-and-instructions). ****This is a child element within "DangerousGoodsInformation"* |
| ***PackingInstructions | **Conditional** | String | **Required for some UN Codes.** The Packing Instructions value must be **valid** (e.g., "P001" or "PI966S1"). Additionally, the Packing Instructions value provided must be valid **for the particular UN Code.** For more information, see [Mercury's DG system documentation](https://mercurydocs.landmarkglobal.com/docs/mercurys-dangerous-goods-system#packing-groups-and-instructions). ****This is a child element within "DangerousGoodsInformation"* |
| ***ItemWeight | **Conditional** | Decimal | This should be the weight for a single quantity of the item (i.e. product). For fulfillment shipments, the sku weight should be used for the item weight value. **Required if the shipment contains DGs.** ****This is a child element within "DangerousGoodsInformation"* |
| ***ItemWeightUnit | **Conditional** | String | The unit used to declare the item weight (i.e. “KG”, “LB”, “OZ”, “G”) **Required if the shipment contains DGs.** ****This is a child element within "DangerousGoodsInformation"* |
| ***ItemVolume | **Conditional** | Decimal | This should be the volume for a single quantity of the item. **Required for some UN Codes.** ****This is a child element within "DangerousGoodsInformation"* |
| ***ItemVolumeUnit | **Conditional** | String | The unit used to declare the item volume (i.e. "ML", "L", "OZ") **Required for some UN Codes.** ****This is a child element within "DangerousGoodsInformation"* |
| **Quantity | Yes | Integer | ***This is a child element within an "Item" element* |
| **UnitPrice | Yes | Decimal | ***This is a child element within an "Item" element* |
| **Description | Yes | String | ***This is a child element within an "Item" element* |
| **HSCode | No | String | ***This is a child element within an "Item" element* |
| **CountryOfOrigin | **Yes** | String | Use 2-character ISO code ***This is a child element within an "Item" element* |
| **ProductIdentifiers | **Conditional** | Container Element | Element to contain an item's specific product identifiers. **Required for international B2C orders delivered to the EU.** ***This is a child element within an "Item" element* |
| ***MerchantProductID | **Conditional** | String | Merchant or seller's own product code. Falls back to Sku if not supplied and sku is provided. ****This is a child element within "ProductIdentifiers"* |
| ***ManufacturerProductID | **Conditional** | String | Manufacturer's non-standardized code as printed on packaging or documentation. ***This is a child element within "ProductIdentifiers"* |
| ***HasStandardizedProductID | **Conditional** | Boolean | Flag for if the product has an industry standard product identifier such as GTIN, UPC, EAN, ISBN, IMEI, etc. ****This is a child element within "ProductIdentifiers"* |
| ***StandardizedProductID | **Conditional** | String | The product's industry standard ID such as GTIN / EAN / UPC / ISBN / IMEI. Leave blank if does not exist. ****This is a child element within "ProductIdentifiers"* |
| ***StandardizedProductIDType | No | String | Optional. The industry standard representing the standardized product ID. If provided, will be used to validate the standardized product ID type. Supported values: "GTIN, EAN, UPC, ISBN, IMEI". ****This is a child element within "ProductIdentifiers".* |
| **CustomsInfo | No | (Container Element) | ***This is a child element within an "Item" element* |
| ***CertificateID | No | String | Optional. Registry Certifier ID in CPSC eFiling ****This is a child element within the "CustomsInfo" element* |
| ***ProductVersionID | No | String | Optional. Product ID version used in CPSC eFiling ****This is a child element within the "CustomsInfo" element* |
| **ContentCategory | No | String | Optional. Supports GOODS, DOCUMENTS, GIFT, RETURNED_GOODS ***This is a child element within an "Item" element* |
| **URL | No | String | Optional. Web address of the item from your storefront. ***This is a child element within an "Item" element* |
| **USMID | **Conditional** | String | Value for a US Manufacturer's Identification Code. **Required for US formal customs entries.** ***This is a child element within an "Item" element* |
| **ManufacturerInformation | **Conditional** | (Container Element) | **Required for US formal customs entries when clearing from Canada via Ground. Minimum of manufacturer name and address required.** ***This is a child element within an "Item" element* |
| ***Name | **Conditional** | String | Manufacturer name. **Required for US formal customs entries when clearing from Canada via Ground.** ****This is a child element within "ManufacturerInformation"* |
| ***Address1 | **Conditional** | String | Manufacturer street address. **Required for US formal customs entries when clearing from Canada via Ground.** ****This is a child element within "ManufacturerInformation"* |
| ***Address2 | No | String | Manufacturer unit/suite number, if applicable ****This is a child element within "ManufacturerInformation"* |
| ***City | **Conditional** | String | Manufacturer city. **Required for US formal customs entries when clearing from Canada via Ground.** ****This is a child element within "ManufacturerInformation"* |
| ***State | **Conditional** | String | Manufacturer state/province. **Required for US formal customs entries when clearing from Canada via Ground.** ****This is a child element within "ManufacturerInformation"* |
| ***PostalCode | **Conditional** | String | Manufacturer postal code. **Required for US formal customs entries when clearing from Canada via Ground.** ****This is a child element within "ManufacturerInformation"* |
| ***Country | **Conditional** | String | Manufacturer country (ISO code). **Required for US formal customs entries when clearing from Canada via Ground.** ****This is a child element within "ManufacturerInformation"* |
| ***Phone | No | String | Manufacturer phone ****This is a child element within "ManufacturerInformation"* |
| ***Email | No | String | Manufacturer email ****This is a child element within "ManufacturerInformation"* |
| **ReturnCustomsInfo | No | (Container Element) | ***This is a child element within an "Item" element* |
| ***HSCode | No | String | The item's HS code ***This is a child element within "ReturnCustomsInfo"* |
| ***HSRegionCode | No | String | ***This is a child element within "ReturnCustomsInfo"* |
| ShipOptions | No |  | For a list of available options, contact your account rep |
| *Name | No | String | Specific shipment option being requested (e.g. signature required). Check with your account rep prior to passing any values. **This is a child element within "ShipOptions"* |
| *Value | No | String | Value for shipment option being selected. Typically true/false **This is a child element within "ShipOptions"* |
| ReturnInformation | No | (Container Element) | Only used when creating return labels. |
| *OutboundShipment | No | String | Used to link this return label to the original outbound shipment **This is a child element within "ReturnInformation"* |
| **Reference | No | String | Send either Reference or TrackingNumber, but not both **This is a child element within "OutboundShipment "* |
| **TrackingNumber | No | String | Send either Reference or TrackingNumber, but not both **This is a child element within "OutboundShipment"* |
| *Condition | No | String | **This is a child element within "ReturnInformation"* |
| *RMANumber | No | String | **This is a child element within "ReturnInformation"* |
| *Notes | No | String | **This is a child element within "ReturnInformation"* |
| *Reason | No | String | If provided, **this text must match a client's pre-configured set of reasons.** Otherwise, it will be classified as a "General Return". **This is a child element within "ReturnInformation"* |
| VendorInformation | **Conditional** | (Container Element) | Conditional. Required if providing third party logistics for the client. Information here represents the actual vendor (retailer) name and address for the items sold in the order. |
| *VendorName | **Conditional** | String | **This is a child element within "VendorInformation"* |
| *VendorPhone | **Conditional** | String | **This is a child element within "VendorInformation"* |
| *VendorEmail | **Conditional** | String | **This is a child element within "VendorInformation"* |
| *VendorAddress1 | **Conditional** | String | **This is a child element within "VendorInformation"* |
| *VendorAddress2 | No | String | **This is a child element within "VendorInformation"* |
| *VendorCity | **Conditional** | String | **This is a child element within "VendorInformation"* |
| *VendorState | **Conditional** | String | **This is a child element within "VendorInformation"* |
| *VendorPostalCode | **Conditional** | String | **This is a child element within "VendorInformation"* |
| *VendorCountry | **Conditional** | String | **This is a child element within "VendorInformation"* |
| *VendorLowValueTaxID | **Conditional** | String | Populate with the vendor's low value tax ID if relevant for tax compliance, such as Norway's VOEC or Australian GST Number **This is a child element within "VendorInformation"* |
| *VendorCCN | **Conditional** | String | Populate with the vendor's commercial clearance (B2B) value if it is being requested **This is a child element within "VendorInformation"* |
| *VendorBusinessNumber | **Conditional** | String | **This is a child element within "VendorInformation"* |
| *VendorRGRNumber | **Conditional** | String | **This is a child element within "VendorInformation"* |
| *VendorIOSSNumber | **Conditional** | String | **This is a child element within "VendorInformation"* |
| *VendorEORINumber | **Conditional** | String | **This is a child element within "VendorInformation"* |
| FulfillmentAddress | No | (Container Element) | Optional. Specifies the ship from address information |
| *Name | **Conditional** | String | **Required when including FulfillmentAddress.** Max 50 characters **This is a child element within "FulfillmentAddress"* |
| *Attention | No | String | Optional. Max 50 characters. **This is a child element within "FulfillmentAddress"* |
| *Address1 | **Conditional** | String | **Required when including FulfillmentAddress.** Max 100 characters. **This is a child element within "FulfillmentAddress"* |
| *Address2 | No | String | Optional. Max 100 characters. **This is a child element within "FulfillmentAddress"* |
| *Address3 | No | String | Optional. Max 100 characters. **This is a child element within "FulfillmentAddress"* |
| *City | **Conditional** | String | **Required when including FulfillmentAddress.** Max 50 characters. **This is a child element within "FulfillmentAddress"* |
| *State | No | String | Max 20 characters **This is a child element within "FulfillmentAddress"* |
| *PostalCode | No | String | Max 10 characters **This is a child element within "FulfillmentAddress"* |
| *Country | **Conditional** | String | **Required when including FulfillmentAddress.** Use 2-character ISO code **This is a child element within "FulfillmentAddress"* |
| SendReturnToAddress | No | (Container Element) | Optional (rare). Allows overriding the default address where the shipment will be sent back to if it is returned. **Contact your integration manager if you plan to use this feature** |
| *Code | No | String | Max length is 32 characters **This is a child element within "SendReturnToAddress"* |
| *Name | No | String | Max 50 characters **This is a child element within "SendReturnToAddress"* |
| *Attention | No | String | Max 50 characters **This is a child element within "SendReturnToAddress"* |
| *Address1 | **Conditional** | String | Max 100 characters **This is a child element within "SendReturnToAddress"* |
| *Address2 | No | String | Max 100 characters **This is a child element within "SendReturnToAddress"* |
| *Address3 | No | String | Max 100 characters **This is a child element within "SendReturnToAddress"* |
| *City | **Conditional** | String | Max 50 characters **This is a child element within "SendReturnToAddress"* |
| *State | **Conditional** | String | Max 20 characters **This is a child element within "SendReturnToAddress"* |
| *PostalCode | **Conditional** | String | Max 10 characters **This is a child element within "SendReturnToAddress"* |
| *Country | **Conditional** | String | Use 2-character ISO code **This is a child element within "SendReturnToAddress"* |
| FreightDetails | **Conditional** | (Container Element) | **Required for all freight shipments** |
| *ProNumber | **Conditional** | String | **Required for all freight shipments** **This is a child element within "FreightDetails"* |
| *PieceUnit | **Conditional** | String | **Required for all freight shipments** **This is a child element within "FreightDetails"* |
| AdditionalFields | No | (Container Element) | Optional. Used to store any other additional information the client wants to pass. Up to 5 additional fields may be passed. |
| *AdditionalField1 | No | String | **This is a child element within "AdditionalFields"* |

#### **ShipRequest**

This endpoint will import a shipment into Mercury and process it with the specified end delivery carrier. On a successful request, you will be given the link to download the label that was generated. Each client has access to a limited number of services, for a list of services available, contact your account representative.

If Landmark cannot return an end carrier label for the shipment a Landmark standard label will be returned instead.

This data import method should not be used if Landmark is facilitating fulfillment. Please see the [**ImportRequest**](https://mercurydocs.landmarkglobal.com/docs/importrequest-api) method.

If the generated label needs to be voided, please use the [**CancelRequest**](https://mercurydocs.landmarkglobal.com/docs/cancelorder-api-request). Note that this will only be possible if the package has not left the client facility yet.

--------

<ShipRequest>

<Login>

<Username>demoapi</Username>

<Password>demo123</Password>

</Login>

<Test>true</Test> *<!-- Optional. Defaults to true before account activation, false afterwards -->*

<ClientID>218</ClientID>

<AccountNumber>L0218A</AccountNumber> *<!--Optional. Only used by clients with multiple account numbers. See integration manager for relevant account numbers -->*

<Reference>3245325</Reference>

<ShipTo>

<Name>Test Company</Name>

<Attention>Test Consignee</Attention> *<!-- Optional -->*

<Address1>1234 Example Drive</Address1>

<Address2>Building #C</Address2> *<!-- Optional -->*

<Address3>Unit 1</Address3> *<!-- Optional -->*

<City>Windsor</City>

<State>ON</State>

<PostalCode>N9A6J3</PostalCode>

<Country>CA</Country> *<!-- Use ISO-3166-2 standard -->*

<Phone>1-519-737-9101</Phone> *<!-- Optional, but encouraged -->*

<Email>orders@test.com</Email> *<!-- Optional -->*

<ConsigneeTaxID>12345</ConsigneeTaxID> *<!-- Optional. For countries that require an individual's tax ID to import as DDP. -->*

</ShipTo>

<ShippingLane> *<!--Allows for fine-grained control over the routing of a shipment.-->*

*<!-- The Region field links the shipment to a Landmark facility combination and is determined on a case-by-case basis. Please contact your Integration Manager for details per shipping facility.-->*

<Region>Landmark CMH</Region>

</ShippingLane>

<ShipMethod>LGINTSTD</ShipMethod>

<OrderTotal>187.98</OrderTotal> *<!-- Conditional. Amount paid by the customer for all the items in their order. Must be passed in instances where the shipment information represents a partial shipment of products comprising a larger order-->*

<OrderInsuranceFreightTotal>20.65</OrderInsuranceFreightTotal> *<!-- Conditional. Amount paid by the customer for shipping their entire order. Must be passed in instances where the shipment information represents a partial shipment of products comprising a larger order-->*

<ShipmentInsuranceFreight>20.65</ShipmentInsuranceFreight> *<!-- Amount charged for shipping and any insurance for the shipment. This value does not include the amount charged for purchased items (i.e. Item Unit Value).-->*

<ItemsCurrency>USD</ItemsCurrency> *<!-- ISO 4217 code to represent the currency (i.e. USD, CAD) -->*

<IsCommercialShipment>0</IsCommercialShipment> *<!-- Optional boolean, and only used in cases when client requires shipments to be commercially cleared (i.e. B2B clearance) -->*

<LabelFormat>PDF</LabelFormat> *<!-- Optional. Default is "PDF". Also supports JPG, GIF, BMP, PNG, and ZPL -->*

<LabelDPI></LabelDPI> *<!--Optional, and only used for ZPL format. Specifies either 203 or 300 DPI images (default is 203 if not provided)-->*

<LabelEncoding>LINKS</LabelEncoding>

*<!-- Optional. Default is "LINKS" unless the LabelFormat is ZPL. For ZPL format, do NOT specify label encoding.*

*LINKS - returns links to all labels which must be retrieved*

*BASE64 - Base64 encoded label image is returned directly in the XML response in <LabelImage> tag.*

*BASE64COMPRESSED - GZcompressed and Base64 encoded label image is returned directly in the XML response in <LabelImage> tag.*

*-->*

<Packages>

<Package>

<WeightUnit>LB</WeightUnit> *<!-- Optional package weight Unit of Measure. Default is LB (pounds). Supports LB, KG, G -->*

<Weight>4.5</Weight> *<!-- Default in LB -->*

<DimensionsUnit>IN</DimensionsUnit> *<!-- Optional package dimension Unit of Measure. Default is IN (inches). Supports IN, CM -->*

<Length>12</Length> *<!--Optional -->*

<Width>12</Width> *<!--Optional -->*

<Height>12</Height> *<!--Optional -->*

<PackageReference>98233312</PackageReference> *<!-- Optional. Another reference for the client -->*

</Package>

</Packages>

<Items>

<Item> *<!-- Required for customs if the shipment will be crossing the border -->*

<Sku>7224059</Sku>

<DangerousGoodsInformation> *<!-- This section is required if item contains* [*dangerous goods*](/v1/docs/mercurys-dangerous-goods-system) *-->*

<ContainsDangerousGoods>1</ContainsDangerousGoods> *<!-- Required. Flag to declare that item contains dangerous goods -->*

<UNCode>UN3481</UNCode> *<!-- Required -->*

<PackingGroup>II</PackingGroup> *<!-- Required for some UN codes -->*

<PackingInstructions>PS967S1</PackingInstructions> *<!-- Required for some UN codes -->*

<ItemWeight>10</ItemWeight> *<!-- Required -->*

<ItemWeightUnit>kg</ItemWeightUnit> *<!-- Required -->*

<ItemVolume>30</ItemVolume> *<!-- Required for some UN codes -->*

<ItemVolumeUnit>ML</ItemVolumeUnit> *<!-- Required for some UN codes -->*

</DangerousGoodsInformation>

<Quantity>2</Quantity>

<UnitPrice>93.99</UnitPrice>

<Description>Women's Shoes</Description>

<HSCode>640399.30.00</HSCode> *<!-- Optional -->*

<CountryOfOrigin>CN</CountryOfOrigin> *<!-- 2 character ISO code -->*

<ProductIdentifiers> *<!-- Conditional. Required for EU-bound low-value B2C sale shipments. -->*

<MerchantProductID>SKU-12345-BLK-M</MerchantProductID> *<!-- Conditional. The seller's product code used for sale. If blank, the 'sku' value will be used. -->*

<ManufacturerProductID>Model: BTP-200X</ManufacturerProductID> *<!-- Conditional. The manufacturer's code used for the product. -->*

<HasStandardizedProductID>1</HasStandardizedProductID> *<!-- Conditional. Boolean value. Indicates if a global industry standard identifier exists for the product. -->*

<StandardizedProductID>8712345678901</StandardizedProductID> *<!-- Conditional. Required if HasStandardizedProductID = 1. Contains the actual industry standard code used for the product. -->*

<StandardizedProductIDType>GTIN</StandardizedProductIDType> *<!-- Optional. GTIN, EAN, UPC, ISBN, IMEI. Will be used to validate Standardized Product ID if passed.-->*

</ProductIdentifiers>

<CustomsInfo>

<CertificateID>SampleCertificateID</CertificateID> *<!-- Optional. Registry Certifier ID in CPSC eFiling -->*

<ProductVersionID>SampleProductVersionID</ProductVersionID> *<!-- Optional. Product ID version used in CPSC eFiling -->*

</CustomsInfo>

<ContentCategory></ContentCategory*> <!-- Optional. Supports GOODS, DOCUMENTS, GIFT, RETURNED_GOODS -->*

<URL></URL> *<!-- Optional. Web address of the item from your storefront -->*

<USMID>CNZHOEAS3ZHON</USMID> *<!-- Value for a US Manufacturer's Identification Code. Required for US formal customs entries -->*

<ManufacturerInformation>

<Name>Example Manufacturer Name</Name> *<!-- Manufacturer name -->*

<Address1>123 Example Street</Address1> *<!-- Manufacturer street address -->*

<Address2>Suite 100</Address2> *<!-- Unit/suite number, if applicable -->*

<City>Shenzhen</City> *<!-- Manufacturer city -->*

<State>Guangdong</State> *<!-- Manufacturer state/province -->*

<PostalCode>518000</PostalCode> *<!-- Manufacturer postal code -->*

<Country>CN</Country> *<!-- Manufacturer country (ISO code) -->*

<Phone>+86-000-0000-0000</Phone> *<!-- Manufacturer Phone-->*

<Email>manufacturer@example.com</Email> *<!-- Manufacturer email -->*

</ManufacturerInformation>

<ReturnCustomsInfo> *<!-- Optional -->*

<HSCode>6403993000</HSCode>

<HSRegionCode>US</HSRegionCode>

</ReturnCustomsInfo>

</Item>

<Item>

<Sku>7224060</Sku>

<Quantity>1</Quantity>

<UnitPrice>53.99</UnitPrice>

<Description>Men's Shoes</Description>

<HSCode>640399.30.00</HSCode>*<!-- Optional -->*

<CountryOfOrigin>CN</CountryOfOrigin> *<!-- 2 character ISO code -->*

<ContentCategory></ContentCategory > *<!-- Optional. Supports GOODS, DOCUMENTS -->*

*<URL></URL> <!-- Optional. Web address of the item from your storefront -->*

</Item>

</Items>

<ShipOptions>

*<!-- Optional. For a list of available options, contact your account rep -->*

<Option>

<Name>dummy_option</Name>

<Value>true</Value>

</Option>

</ShipOptions>

<ReturnInformation> *<!-- Optional. Only used when creating return labels. -->*

<OutboundShipment> *<!-- Optional. Used to link this return label to the original outbound shipment ->*

<Reference>12932</Reference> *<!-- Send either Reference or TrackingNumber, but not both -->*

<TrackingNumber>LTN123212</TrackingNumber>

</OutboundShipment>

<Condition>Damaged</Condition> *<!-- Optional -->*

<RMANumber>RMA12321</RMANumber> *<!-- Optional -->*

<Notes>The shipment was damaged in transit.</Notes> *<!-- Optional -->*

<Reason>Did Not Want</Reason> *<!-- Optional. If provided, this text must match a client's pre-configured set of reasons. Otherwise it will be classified as a "General Return". -->*

</ReturnInformation>

<VendorInformation> *<!-- Conditional. Required if providing third party logistics for the client. Information here represents the actual vendor (retailer) name and address for the items sold in the order. -->*

<VendorName>Test Company Legal Name</VendorName>

<VendorPhone>12223334444</VendorPhone>

<VendorEmail>contact@vendor.com</VendorEmail>

<VendorAddress1>Sample Company Street</VendorAddress1>

<VendorAddress2>Suite 135</VendorAddress2>

<VendorCity>Santa Barbara</VendorCity>

<VendorState>CA</VendorState>

<VendorPostalCode>93101</VendorPostalCode>

<VendorCountry>US</VendorCountry>

<VendorLowValueTaxID>VOEC0123456</VendorLowValueTaxID> *<!--Populate with the vendor's low value tax id if relevant for tax compliance, such as Norway's VOEC or Australian GST Number-->*

<VendorCCN>12345678RM0001</VendorCCN> *<!--Populate with the vendor's commercial clearance (b2b) value if it is being requested-->*

<VendorBusinessNumber>12345</VendorBusinessNumber>

<VendorRGRNumber>123</VendorRGRNumber>

<VendorIOSSNumber>IM1234567891</VendorIOSSNumber>

<VendorEORINumber>12345</VendorEORINumber>

</VendorInformation>

<FulfillmentAddress> *<!-- Optional. Specifies the ship from address information -->*

<Name>Client Warehouse</Name> *<!-- Required when including FulfillmentAddress, Max 50 characters. -->*

<Attention>Returns Dept.</Attention> *<!-- Optional. Max 50 characters. -->*

<Address1>12 Sample St.</Address1> *<!-- Required when including FulfillmentAddress, Max 100 characters. -->*

<Address2>Suite BA</Address2> *<!-- Optional. Max 100 characters. -->*

<Address3></Address3> *<!-- Optional. Max 100 characters. -->*

<City>Kitchener</City> *<!-- Required when including FulfillmentAddress, Max 50 characters. -->*

<State>ON</State> *<!-- Max 20 characters. -->*

<PostalCode>N2H 4B4</PostalCode> *<!-- Max 10 characters. -->*

<Country>CA</Country> *<!-- Required when including FulfillmentAddress, 2 character ISO code -->*

</FulfillmentAddress>

<SendReturnToAddress> *<!-- Optional (rare). Allows overriding the default address where the shipment will be sent back to if it is returned. Contact your integration manager if you plan to use this feature. -->*

<Code>GHB78</Code> *<!-- Optional. Max length is 32 characters. -->*

<Name>Client Warehouse</Name> *<!-- Max 50 characters. -->*

<Attention>Returns Dept.</Attention> *<!-- Optional. Max 50 characters. -->*

<Address1>12 Sample St.</Address1> *<!-- Max 100 characters. -->*

<Address2>Suite BA</Address2> *<!-- Optional. Max 100 characters. -->*

<Address3></Address3> *<!-- Optional. Max 100 characters. -->*

<City>Kitchener</City> *<!-- Max 50 characters. -->*

<State>ON</State> *<!-- Max 20 characters. -->*

<PostalCode>N2H 4B4</PostalCode> *<!-- Max 10 characters. -->*

<Country>CA</Country> *<!-- 2 character ISO code -->*

</SendReturnToAddress>

<FreightDetails> *<!-- Required for all freight shipments -->*

<ProNumber>LGBR020409E</ProNumber>

<PieceUnit>Pallet</PieceUnit>

</FreightDetails>

<AdditionalFields> *<!-- Optional. Used to store any other additional information the client wants to pass. Up to 5 additional fields may be passed. -->*

<Field1>Any type of data</Field1> *<!-- Optional -->*

<Field2>Purchased with Credit Card</Field2> *<!-- Optional -->*

<Field3>99000029327172321</Field3> *<!-- Optional -->*

<Field4>123198012</Field4> *<!-- Optional -->*

<Field5>Stored information</Field5> *<!-- Optional -->*

</AdditionalFields>

</ShipRequest>

#### **ShipResponse**

<ShipResponse>

<Errors> *<!-- Only if Error(s) occur is this element included --*>

<Error>

<ErrorCode>State</ErrorCode>

<ErrorMessage>State-Province is invalid, must be 2 characters.</ErrorMessage>

</Error>

</Errors>

<Test>true</Test> *<!-- Only present if the API call was to the test environment -->*

<Result>

<Success>true</Success>

<ResultMessage>Shipment 3245325 was successfully processed.</ResultMessage>

<ShippingCarrier>Canada Post</ShippingCarrier> *<!-- The name of the end-delivery carrier -->*

<AddressCorrections>

*<!-- Only if the address was modified during the call -->*

<Correction>

<ModifiedField>PostalCode</ModifiedField>

<OldValue>M9A6J3</OldValue>

<NewValue>N9A6J3</NewValue>

</Correction>

</AddressCorrections>

<ShipmentLabelLink>https://api.landmarkglobal.com/download/get-label.php?hid=5SalTlxR8JkpE%2FCW4HxGD0ghMOXXA%2F0rebjGm9EeaVlkG58%3D_5KAZZsOEn9E4p5Sy</ShipmentLabelLink> *<!-- Contains all package labels. Only available if encoding type is LINKS and PDF is requested -->*

<Packages>

<Package>

*<!-- If LabelEncoding is LINKS, return links to all package labels.*

*More than one LabelLink may be returned if multiple labels are needed on the box -->*

<LabelLink>https://api.landmarkglobal.com/download/get-label.php?hid=D90EMhtHMjLX8oyitCBWwzTS0ja2b5wmOhZ6u8lGCBCbcfo%3D_1UDpnv5E0kJlBMsB</LabelLink>

<LabelLink>https://api.landmarkglobal.com/download/get-label.php?hid=gGWWHlyiFzHmu4UNXzpYtFX8yQouITzjOxk20t%2FXtHQLmLY%3D_%2BuTpb%2FIp7UxYxdxB</LabelLink>

*<!-- If LabelEncoding is not LINKS, return the encoded label image directly.-->*

<LabelImages>

*<!-- If the label requires multiple pages, there may be more than one LabelImage -->*

<LabelImage>23987B3KD0LK211AF......</LabelImage> *<!-- Encoded label image string -->*

<LabelImage>03ASDFLJKDFS32ED......</LabelImage> *<!-- Encoded label image string -->*

</LabelImages>

<TrackingNumber>8543976432</TrackingNumber> *<!-- Carrier end delivery tracking number -->*

<LandmarkTrackingNumber>LTN123456N1</LandmarkTrackingNumber>

<PackageReference>98233312</PackageReference> *<!-- Will be sent back if provided in request -->*

<BarcodeData>2MAJ5328953205289</BarcodeData>

</Package>

</Packages>

</Result>

</ShipResponse>

#### **Possible Errors**

This table lists all errors that may be returned by the ShipRequest API endpoint. [Brackets] in the ErrorMessage are used to represent to the value passed for the related element. An example is provided when an ErrorMessage is variable.

| Related Element(s) | ErrorMessage | Details/Action |
| --- | --- | --- |
| General Errors |
| User, API | User [username] does not have permissions to this API |  |
| Failure authenticating user |  |
| User is not available. Check your username/password |  |
| N/A | Unable to parse characters | Ensure that special characters are properly encoded and an encoding flag is included in your XML header. *Example:* <?xml version=""1.0"" encoding=""UTF-8""?> *Example:* <?xml version=""1.0"" encoding=""ISO-8859-1""?> |
| <Login> Errors |
| Login | Required element Login not found | Provide login credentials and verify the XML can be parsed |
| Login name not provided |
| User, ClientID | Request is missing client ID |  |
| Unable to authenticate the user credentials |  |
| Client is inactive |  |
| Client has been deactivated. Permission denied |  |
| User [username] does not have permissions to client: [clientID] |  |
| Unable to determine desired client for this user | If user has access to more than one client, the ClientID is required |
| Username, password | The username/password combination provided is invalid |  |
| The username/password combination provided is disabled |  |
| Password not provided |  |
| Missing Element Errors |
| Varies by API | *Format:* Required element [Missing Element] not found *Example:* Required element Reference not found | Required elements for ShipRequest include Reference, ShipMethod, ShipTo, Name, Address1, City, State, PostalCode, Country, Packages, Package, Weight, Sku and Quantity |
| Address Errors |
| Name, Address1, City, State, PostalCode, Country | *Format:* Invalid address field: [invalid field] *Example:* Invalid address field: name | **State:** For Australia, Canada, Chile and US, please use 2-digit ISO code for the State value. For Hungary and Singapore, remove State value **PostalCode:** Confirm value is in the correct format for the destination country **Country:** Use 2-digit ISO country code |
| Country required |  |
| City, State, PostalCode | At least one of Postal, State, or City required |  |
| *Example:* Possible resolutions - Suggested Cities: EDMONDS, WOODWAY; Suggested Postal Codes: 6056, 98004, 98005, 98006 | If an address is invalid, possible resolutions are returned, including states, cities and/or postal codes. |
| City, State, Postal Code do not match | Address validation could not make a suggestion. Confirm city, state and postal code values |
| Errors Specific to ShipRequest API |
| Reference | Invalid customer reference number | Reference numbers should be alphanumeric and 50 characters or less |
| Reference or TrackingNumber is required in ReturnInformation-OutboundShipment, neither found |  |
| ShipMethod | The client does not have access to the requested shipping service: [ShipMethod] | Confirm ShipMethod values with Integration Manager |
| Invalid shipping service requested: [ShipMethod] |
| LabelFormat | *Example:* Invalid label format [LabelFormat] requested. Support image types are pdf, jpg, gif, png, bmp, zpl. | Supported image types may change. |
| LabelEncoding | Invalid label encoding [LabelEncoding]. With LabelFormat ZPL, must use label format ZPL or omit the tag. |  |
| AccountNumber | Invalid account number: [account number] |  |
| VendorName, VendorAddress1, VendorCity, VendorCountry | *Example:* No vendor name specified for [Reference], required if providing third party logistics | Error is returned if one of these elements is included but the others are blank VendorInformation is required for 3PLs (third-party logistics) |
| Country | Client is not set up for delivery to [country name] |  |
| CartIntegration | This client is not enabled for cart integration, so the CartIntegration tag is not allowed. To enable cart/payment integration, contact IT support |  |
| Items | This shipment has no items. One or more is required to process. | At least one item is required for all orders |
| Sku | Invalid sku provided for [item element number] | Max length is 64 characters. Use a unique, alphanumeric value and remove special characters other than: - _ |
| The sku [sku name] is already stored as a standard, non-virtual sku, thus it cannot be considered a virtual sku now. |  |
| Quantity | Invalid quantity provided for [sku name] in [item element number] | Requires integer value |
| UnitPrice | Invalid unit price provided for [sku name] in [item element number] | Use real item value |
| Description | Invalid description provided for [sku name] in [item element number] | Max length is 255 characters |
| CountryOfOrigin | Invalid country of origin provided for [sku name] in [item element number] | Use 2-digit ISO country code |
| InsuredValue | Please provide floating point value with a dot as decimal separator or integer e.g. 1.0 or 1 |  |
| Weight | Pieces of this weight ([package weight]) are not supported when shipping to [country name] |  |
| WeightUnit | Invalid or unsupported "WeightUnit" provided on Package [element number] | Supported WeightUnits include LB, KG, G. Defaults to LB if not specified. |
| Dimensions | Pieces with these dimensions [length x width x height] are not support when shipping to [additional error detail] |  |
| DimensionsUnit | Invalid or unsupported "DimensionsUnit" provided on Package [element number] | Supported DimensionsUnits include IN, CM. Defaults to IN if not specified. |
| Freight | Element FreightDetails is required for freight shipments |  |
| Invalid piece unit type provided: [piece unit] |  |
| N/A | Error adding shipment to batch |  |
| Error loading shipping service validator |  |
| The shipment reference [reference number] was already used by [duplicated LTN] on [date] |  |
| The referenced original shipment does not exist or does not contain the same items as this shipment | May occur when reshipping |
| Failed to find the original outbound order with the information provided. Finding a match is required when using the "retrieve_consignee_data_from_outbound" option. |  |

The recipient of a shipment. The consignee might also be called the end-consumer. This could be an individual customer, someone ordering a commercial shipment to resell, or a business.

A shipment that is returned by the end-consumer and that gets a specific treatment depending on the client's instructions.

Business to Business. Refers to when a package is shipped to a business (rather than an individual consumer).

An article in a shipment. There may be multiple items in a single package. Items are characterized by their sku, HS code, quantity, price per article, etc. Some items, such as welcome packs or starter kits, may contain multiple components.

An authority or agency in a country responsible for collecting tariffs and for controlling the flow of goods, including animals, transports, personal effects, and hazardous items, into and out of a country.

A sku, short for Stock Keeping Unit, is a unique item number for a company's product.

Articles or substances capable of posing a significant risk to health, safety or property, and that ordinarily require special attention when being transported. Often abbreviated to DG

Dangerous Goods. Articles or substances capable of posing a significant risk to health, safety or property, and that ordinarily require special attention when being transported.

Also called "United Nations Number". Four-digit numbers set by the UN that identify dangerous goods, hazardous substances and articles (such as explosives, flammable liquids, toxic substances, etc.) in the framework of international transport.

Specifications for packaging dangerous goods for air transport set by the International Air Travel Association (IATA).

Consumer Product Safety Commission, a U.S. governmental regulatory agency

An internationally standardized tariff code used to classify goods for customs. HS codes are also sometimes called tariff classifications. These codes describe products very specifically so that they can clear customs and be taxed appropriately, and they are required for any product being shipped internationally. Each country, however, has a different set of codes that they allow, so a particular product may have its sku harmonized to (associated with) different HS codes for different countries.