Cancel API Request
- 12 Aug 2022
- 4 Minutes to read
- Contributors
- Print
- DarkLight
Cancel API Request
- Updated on 12 Aug 2022
- 4 Minutes to read
- Contributors
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
The following details how to cancel a carrier label with Mercury via an API request. The Cancel API request unprocesses shipments and also has the option to delete them. This request is typically used alongside ShipRequest in cases where the client does not use a generated label.
The Cancel API request should not be confused with the CancelOrder API request, which is used to cancel and delete fulfillment orders.
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/Cancel.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.
CancelRequest
This request will void a label of a processed shipment. The label cannot be used to send a shipment after a successful CancelRequest and the client will not be charged for the shipment. Depending on the service used, there will be a different window to unprocess the shipment. After manifesting, however, no shipment can be unprocessed.
To delete the shipment in addition to unprocessing it, set the optional <DeleteShipment> tag to true. Even if the shipment is already canceled(unprocessed), this flag can still attempt to delete the shipment.
This would typically be used after a ShipRequest call, and before the package leaves the client's facility.
--------
<CancelRequest> <!-- A cancel request will cancel ALL packages under a shipment, even if only one tracking number is passed. -->
<Login>
<Username>demoapi</Username>
<Password>demo123</Password>
</Login>
<Test>true</Test> <!-- Optional. Defaults to true before account activation, false afterwards -->
<ClientID>218</ClientID> <!-- Required if more than one client under user, otherwise Optional -->
<!-- Either Reference OR TrackingNumber is required but not both -->
<Reference>3245325</Reference>
<TrackingNumber>7237529100002194</TrackingNumber>
<DeleteShipment>true</DeleteShipment> <!--Optional-->
<Reason>Consignee canceled shipment.</Reason> <!--Required if deleting a shipment.-->
</CancelRequest>
CancelResponse
<CancelResponse>
<Errors> <!-- Only if Error(s) occur is this element included -->
<Error>
<ErrorCode>Duplicate</ErrorCode>
<ErrorMessage>More than one shipment found with that reference (use TrackingNumber).</ErrorMessage>
</Error>
</Errors>
<Result>
<Success>true</Success>
<ResultMessage>Successfully unprocessed and deleted shipment with reference 3245325</ResultMessage>
</Result>
</CancelResponse>
Possible Errors
This table lists all errors that may be returned by the Cancel 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 | ||
Errors Specific to Cancel API | ||
| Reference | Either Reference or TrackingNumber is required, neither found | |
| Shipment | Insufficient data provided to determine shipment. Must provide a valid reference or tracking number | |
| Could not find shipment with [reference/tracking number] in our system | ||
| Duplicate results found for [reference/tracking number] Could not unprocess shipment | ||
| Failed to find shipment | ||
| No shipment specified. Cannot unprocess | ||
| N/A | Already assigned to Shipment Group | |
| Already manifested | ||
| Successfully unprocessed the shipment, but failed to delete it. Deletion errors are provided in subsequent Error tags. | ||
Was this article helpful?