Shipments Cancellation

Intro Request Format Request OAuth Format Response Format Status Codes Examples

If it is necessary to cancel a shipment, Mercado Libre will make a PUT call to the authorization URL:

PUT service_url/shipments/shipment_id/authorization

Note:

Idempotence: in case of receiving a request with a shipment already cancelled, the service must retrieve a response with “HTTP Code” = 200, the same body and tracking number that was retrieved during the original cancellation.
A cancelled shipment could be authorized in a future so this flow should be taken into account.
When a shipment is already in possession of the carrier, if a cancellation is requested, the package should be blocked and the return flow begins.

Depending on whether the cancellation was succesfuly or not, it is expected that the carrier retrieves a result according to the specified at "Status Code" section. In case of error, the communication will be retried according to the retry schema defined as part of the integration.

Important:

OAuth 2.0 will be used for securing cancellation.

Formato Request

As part of the body a JSON object with the following fields will be sent:

Name	Data type	Description
status	String	Contains status value. CANCEL
tracking_number	String	Shipment identifier provided by the carrier once it was authorized.

OAuth Request Format

For the authentication mechanism through the generation of a token with OAuth, the following header must be added to the request:

--request  PUT 'https://hostname/shipments/{shipment_id}/authorization'
--header 'Authorization: Bearer + TOKEN'
--body 'What is described in each integration is maintained'

Note:

Once the OAuth solution is implemented, the use of username and password in the integrations should be deprecated in favor of the use of the token. The fields to be deprecated are the following:

Field	Type	Description
carrier_information.user	String	Identifies a mail system user assigned to the Mercado Libre customer.
carrier_information.password	String	Identifies the password associated with the system user.

Response Format

As part of the body, the result of the cancellation will be retrieved as follows:

Name	Data type	Description	Type
status	String	Status of the cancellation request. CANCELLED FAILED ERROR	Mandatory.
status_message	String	Any relevant detail related to the status.	Mandatory in case of error.
tracking_number	String	Shipment identifier.	Mandatory.

Status Codes

Status	Status Message	HTTP Code	Description	Action
CANCELLED	-	200	When cancellation was succesfuly processed	Shipment was already cancelled and there won't be retry.
CANCELLED	BLOCKED	200	For the scenario of blocking packets held by the carrier, it is expected that it will return "status": "CANCELLED" together with the "status_message": "BLOCKED".	Block the delivery and start the return flow.
FAILED	-	400	When the cancellation was not able to be processed beacause an error in the request. It is expected that “status”: “FAILED” will be retrieved together with “status_message” describing the error.	Depending on the error nature, an attemp will be made to correct the data before processing the request again. Periodic retries could occur.
ERROR	-	500	Any error at server side. In this case , status and satus_message are optional.	It will retry indefinitely until a satisfactory response is obtained according to the defined retry scheme

Examples

Request:

{
  "carrier_information": {
    "account": "A432765637",
    "contract": "000123ABC87",
    "user": "",
    "password": "pa$word",
    "client_id": "432765637"
  },
  "status": "CANCEL",
  "tracking_number": "1234NLUG123"
}

Response:

Cancelled (200 OK)

{
  "status":"CANCELLED",
  "status_message":"",
  "tracking_number": "1234NLUG123"
}

Blocked (200 OK)

{
  "status":"CANCELLED",
  "status_message":"BLOCKED",
  "tracking_number": "1234NLUG123"
}

Failed (400 FAILED)

{
  "status":"FAILED",
  "status_message":"Invalid tracking number",
  "tracking_number": "1234NLUG123"
}

Error (500 ERROR)

{
  "status":"ERROR",
  "status_message":"Internal error occurred",
  "tracking_number": "1234NLUG123"
}