ShipRequest API
- 15 Nov 2024
- 16 Minutes to read
-
Contributors
-
Print
-
DarkLight
ShipRequest API
- Updated on 15 Nov 2024
- 16 Minutes to read
-
Contributors
-
Print
-
DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
The following details how to import shipment data to Mercury via an API request.
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
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
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 method.
If the generated label needs to be voided, please use the CancelRequest. 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> <!-- Optional, 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 and PNG -->
<LabelEncoding>LINKS</LabelEncoding>
<!-- Optional, default is "LINKS".
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.
-->
<ShipOptions>
<!-- Optional, For a list of available options, contact your account rep -->
<Option>
<Name>dummy_option</Name>
<Value>true</Value>
</Option>
</ShipOptions>
<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 compliane, 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>
<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>
<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>
<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>
<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 -->
<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 -->
<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 -->
<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>
<FreightDetails> <!-- Required for all freight shipments -->
<ProNumber>LGBR020409E</ProNumber>
<PieceUnit>Pallet</PieceUnit>
</FreightDetails>
</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>
</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 ImportRequest 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. | ||
Was this article helpful?