Tracking Notifications

Introduction

When a shipment's status changes, the carrier must inform Mercado Libre of this transition by sending a corresponding event notification. There are two ways to report the event recorded for a shipment:

PUSH: The carrier sends the corresponding event notification to our tracking endpoint.
PULL: The carrier exposes all notifications already recorded for the shipment via API.

In all cases, the objective is to ensure alignment with the carrier on the shipment's current status and the events already recorded. The notifications must reflect the actual transportation sequence and arrive in chronological order. Mercado Libre uses notification codes (code) associated with carrier event codes (carrier_code) to receive and validate each event. It is critical to follow the notification flow and the order in which events occur, because some status codes are considered final. Once a notification for a final state is received, any subsequent events after that status will be disregarded.

Notifications Payload

Important: Some fields are mandatory depending on the notification code sent. Push and Pull notifications payload must contain the same information.

Notification Fields

The fields that can be included in the notification payload are:

Name	Type of data	Description	Type
tracking_number	String	Shipping identifier.	Mandatory
code	String	Event code.	Mandatory
carrier_code	String	Carrier internal event code.	Mandatory
payload	Node	Contains information relevant to a particular event.
payload.date	Date (ISO8601)	Event occurrence date. Valid values: UTC 2024-07-04T12:08.235Z or relative local time 2024-07-04T12:08.235-07.	Mandatory
payload.reason	String	Indicates the specific reason associated with the reported code, providing predefined additional information that explains the occurrence of the event. Possible values of 'reason' for code 0114: establishment_not_found waiting_time_exceeded establishments_closed load_capacity_exceeded address_unsafe already_picked_up delivery_cancelled delivery_not_found payment_requested other_pickup_problems Possible values of 'reason' for code CBT-0272: oversize overweight overprice prohibited_item other	Mandatory for code 0114 (Proximity) or CBT-0272 (Consolidation)
payload.comment	String	Additional information on the status code.	Optional
payload.flight.awb	String	Air Waybill Number	Optional
payload.declaration_number	String	Pedimento Number/Customs Document Number	Mandatory for code CBT-0283
payload.agency_id	String	Agency identification code.	Mandatory codes CBT-0201 and CBT-0215.
payload.agency.phone_number	String	Agency phone number where the package can be picked up. The format must be a number of up to fifteen digits that begins with "+". [+] [country code] [subscriber number including area code]. Example: +541142345678	Only available for notifications CBT-0215 of CBT
payload.cost	BigDecimal	Shipping item cost.	Mandatory for codes CBT-0260 and CBT-0265.
payload.location	Node	Contains information relevant to the location where the event occurred.
payload.location.zip_code	String	ZIP code where the event occurred.	Optional
payload.location.country_id	String	Country id where the event occurred. ISO 3166 for country names.	Mandatory for codes with prefix "CBT"
payload.location.state_name	String	Name of state / province where the event occurred.	Optional
payload.location.city_name	String	Name of city where the event occurred.	Optional
payload.location.neighborhood_name	String	Name of neighborhood where the event occurred.	Optional
payload.location.facility	String	Identifier of the Logistics Center where the event occurred.	Optional
payload.location.geolocation	Node	Geolocation of the place where the event occurred.	Optional
payload.location.geolocation.geolocation_type	String	Geolocation accuracy provided. May contain any of the following values: APPROXIMATE: approximate geolocation. GEOMETRIC_CENTER: the center of a region that is used as a reference is located. RANGE_INTERPOLATED: constrains precision to midpoint of 2 nearby reference points. ROOFTOP: Indicates that the location is exact. UNKNOWN: Indicates that the location was not validated.	Optional
payload.location.geolocation.latitude	BigDecimal	Latitude of geolocalization.	Optional
payload.location.geolocation.longitude	BigDecimal	Longitude of geolocalization.	Optional
payload.dimensions	Node
payload.dimensions.height	BigDecimal	In centimetres.	Optional
payload.dimensions.width	BigDecimal	In centimetres.	Optional
payload.dimensions.length	BigDecimal	In centimetres.	Optional
payload.dimensions.weight	BigDecimal	Gross weight in grams.	Mandatory for code CBT-0260
payload.redispatch	Node		Optional
payload.redispatch.tracking_number	String	Redispatch carrier shipment identifier.	Optional
payload.redispatch.carrier_id	BigDecimal	Redispatch carrier identifier defined by Mercado Libre.	Optional
payload.redispatch.tracking_url	String	Web tracking URL of the redispatch carrier.	Optional
payload.estimated_delivery_date	Date (ISO8601)	Estimated delivery date of shipment. Valid values: UTC 2024-07-04T12:08.235Z or relative local time 2024-07-04T12:08.235-07.	Mandatory for codes CBT-0265.
payload.estimated_pickup_date	Date (ISO8601)	Estimated pick-up date of shipment. Valid values: UTC 2024-07-04T12:08.235Z or relative local time 2024-07-04T12:08.235-07.	Mandatory for codes CBT-0265 and CBT-0133.
payload.proof_of_delivery	Node		Optional
payload.proof_of_delivery.receiver_document	Node		Optional
payload.proof_of_delivery.receiver_document.type	String	Type of identity document of the person who receives the package. Valid values: CI: Identification Card. PASSPORT CPF: Individual Registration. RG: General Registration. CURP: Unique Population Registration Key. INE_IFE: National Electoral Institute. LICENCIA: Driver License. RFC: Federal Register of Taxpayers. RUT: Sole Tax Roll. CC: Citizen Card. DNI: National Identity Document.	Mandatory
payload.proof_of_delivery.receiver_document.number	String	Identity document number of the person who receives the package.	Mandatory
payload.proof_of_delivery.receiver_last_name	String	Surname of the person who receives the package.	Optional
payload.proof_of_delivery.receiver_name	String	Name of the person who receives the package.	Optional
payload.proof_of_delivery.receiver_relationship	String	Who received the package. Valid values: BUYER FAMILY NEIGHBOUR DOORMAN RECEPTION FRIEND HOLDER OTHER	Optional
payload.proof_of_delivery.image	String	Image of receiver signature containing the full name and document number. The image must be sent encoded in Base64.	Optional
payload.driver	Node	Provider delivery information	Optional
payload.driver.id	String	Id of the delivery person in the carrier's registration	Mandatory for code 0133
payload.driver.name	String	Delivery person name	Mandatory for code 0133
payload.driver.email	String	Delivery person email	Optional
payload.driver.phone	String	Delivery person phone number. The format must be a number of up to fifteen digits that begins with "+". [+] [country code] [subscriber number including area code]. Example: +541142345678	Optional
payload.driver.license_plate	String	Delivery vehicle identification	Optional
payload.vehicle	Object	Vehicle information for the delivery	Optional
payload.vehicle.reference_type	String	Type of information related to the vehicle, which can be: ID: id of the delivery person in the carrier's registration LICENSE_PLATE: delivery vehicle identification	Optional
payload.vehicle.reference	String	Information about the field payload.vehicle.reference_type	Optional
payload.consolidated_packages	Node	Node containing information about the consolidation.	Mandatory for code CBT-0272
payload.consolidated_packages.consolidation_id	String	Identification sent in the consolidation flow.	Mandatory for code CBT-0272
payload.consolidated_packages.tracking_number	String	Tracking number assigned to the consolidation.	Mandatory for code CBT-0272
payload.consolidated_packages.shipments	List	List of shipment IDs included in the consolidation.	Mandatory for code CBT-0272
payload.details.transport.content.restricted_item_type	String	Used to identify the type of special goods are included inside the package. Valid values are: CREAM, LIQUID, POWDER, BATTERY	Mandatory for code CBT-0270

Payload Example

json
1{
2  "tracking_number":string,
3  "code":string,
4  "carrier_code":string,
5  "payload":{
6    "date":string (ISO8601),
7    "reason":string,
8    "comment":string,
9    "flight":{
10      "awb":string
11    },
12    "declaration_number":string,
13    "agency_id":string,
14    "agency":{
15      "phone_number":string
16    },
17    "cost":number,
18    "location":{
19      "zip_code":string,
20      "country_id":string,
21      "state_name":string,
22      "city_name":string,
23      "neighborhood_name":string,
24      "facility":string,
25      "geolocation":{
26        "geolocation_type":string,
27        "latitude":number,
28        "longitude":number
29      }
30    },
31    "dimensions":{
32      "height":number,
33      "width":number,
34      "length":number,
35      "weight":number
36    },
37    "redispatch":{
38      "tracking_number":string,
39      "carrier_id":number,
40      "tracking_url":string
41    },
42    "estimated_delivery_date":string (ISO8601),
43    "estimated_pickup_date":string (ISO8601),
44    "proof_of_delivery":{
45      "receiver_document":{
46        "type":string,
47        "number":string
48      },
49      "receiver_last_name":string,
50      "receiver_name":string,
51      "receiver_relationship":string,
52      "image":string
53    },
54    "driver":{
55      "id":string,
56      "name":string,
57      "email":string,
58      "phone":string,
59      "license_plate":string
60    },
61    "vehicle":{
62      "reference_type":string,
63      "reference":string
64    },
65    "consolidated_packages":{
66      "consolidation_id":string,
67      "tracking_number":string,
68      "shipments":array
69    },
70    "details":{
71      "transport":{
72        "content":{
73          "restricted_item_type":string
74        }
75      }
76    }
77  }
78}

Note: Send all available "location" data. The most valuable location data is the "geolocation" node.

Push Notifications

Important: For security in push tracking, OAuth will be used. Please check the required fields that must be sent according to the specified event.

Request

Shipments

The shipment notifications must be sent to this endpoint:

bash
1POST 'https://api.mercadolibre.com/shipments/{shipmentId}/notifications' \ --header 'Authorization: Bearer {accessToken}'

Handling Units

The HU notifications must be sent to this endpoint:

bash
1POST 'https://api.mercadolibre.com/tracking/{id}/notifications' \ --header 'Authorization: Bearer {accessToken}'

Response

Successful

If the notification was received successfully, the POST returns status OK.

json
1{
2  "status": "OK"
3}

Failed (4XX FAILED)

If the HTTP error code is type 4XX, it should not be reattempted (as there is some problem with the request).

json
1{
2  "message": "User must have a valid scope",
3  "error": "invalid_scopes",
4  "status": 403,
5  "cause": null,
6  "internal_cause": [ ]
7}

Error (500 ERROR)

If the HTTP error code is of type 5XX, it must be reattempted using some backoff mechanism with at least three retries.

json
1{
2  "message": "Internal server error",
3  "error": "internal_server_error",
4  "status": 500,
5  "cause": null,
6  "internal_cause": [ ]
7}

Test Notifications

To send a test notification, it will be necessary: Valid credentials (access token) to the stage environment. Notification mappings validated and created in the stage environment. Shipment created with a "test" tag. The shipment test notifications must be sent to this endpoint:

bash
1POST 'https://api.mercadolibre.com/stage/shipments/{shipmentId}/notifications' \--header 'Authorization: Bearer {accessToken}'

Note: To create a test shipment, please contact the Integrations or Tracking team.

Pull Notifications

The carrier should provide an HTTP REST endpoint to retrieve the shipment events as the specification details as follows.

Important: We recommend that the number of shipments consulted be at least 50. For security in pull tracking, OAuth will be used. Inside the request body, a JSON will be sent with the following attributes:

OAuth Request Format

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

bash
1--request POST 'https://hostname/tracking'
2--header 'Authorization: Bearer TOKEN'
3--body 'What is described in each integration is maintained'

Inside the request body, a JSON will be sent with the following attributes:

Name	Type of data	Description	Type
id	Long	Unique identifier of the shipment used by Mercado Libre, required to authorize. This ID will later be used to notify the events that occur in the operational flow of the shipment.	Mandatory
tracking_number	String	Shipping identifier.	Mandatory

json
1[
2  {
3   "id": long,
4   "tracking_number": string
5  },
6  {
7    "id": long,
8    "tracking_number": string
9  }
10]

Response Format

Note: Push and Pull notifications payload must contain the same information. If there are no events for a shipment, or the tracking number does not exist on your side, the "events" node will be empty.

Successful

Should be returned when the request was successfully processed.

json
1[
2  {
3    "id":26379079680,
4    "tracking_number":"1234NLUG123",
5    "events":[
6      {
7        "code":"0227",
8        "carrier_code":"a31",
9        "payload":{
10          "date":"2017-05-22T00:00:00-04:00",
11          "comment":"Out for delivery",
12          "location":{
13            "geolocation":{
14              "geolocation_type":"ROOFTOP",
15              "latitude":-32.96234,
16              "longitude":-60.64053
17            }
18          }
19        }
20      }
21    ]
22  }
23]

Error response format

Name	Type of data	Description
status	Integer	Error code. Matches the http status code.
message	String	Any details relevant to the state. Mandatory in case of failure.
error	String	http status error message in snake_case.
cause	Array	List of errors

Failed (4XX FAILED)

Should be returned when the request could not be processed due to an error in the request.

json
1{
2  "status":403,
3  "message":"User must have a valid scope",
4  "error":"invalid_scopes",
5  "cause":null
6}

Error (500 ERROR)

Should be returned due to any server side error.

json
1{
2  "message":"DB is not available",
3  "error":"server_error",
4  "status":500,
5  "cause":[]
6}

Notifications Mapping

The mappings link the event codes used by carriers (carrier_code) with Mercado Libre's standardized internal codes (code). They are essential for validating, standardizing, and correctly processing received tracking notifications, ensuring that the shipment status is updated.

Definitions: carrier_code: event code as sent by the carrier. code: standardized notification code of Mercado Libre.

Note: A notification may be related to several event codes from a carrier, just as a carrier event code may be related to more than one MELI notification, according to the rules and events that may be reported by the carrier (e.g., variations by flow, delivery problems, incidents, etc.).

Invalid Mappings Impact

If a notification is received with incorrect mapping, the corresponding event will be ignored and the delivery status will not be updated. It is necessary to communicate code changes in advance to avoid discarding important notifications and to ensure there are no inconsistencies in the package lifecycle.

How to create or change a mapping

The Tracking Core team is responsible for managing and maintaining the internal mapping database and ensuring that received updates are consistent with the actual movement of the package. To create, adjust, or disregard a mapping, send an email to: shipping_tracking_it@mercadolivre.com following these guidelines: Subject: [MercadoLibre][carrier-name] Mapping Adjustment/Creation In the body of the email, be sure to include: Carrier name and country; Carrier event code and corresponding MELI update code; Justification for the mapping change or creation; Expected start date for sending updates after the adjustment.

Tracking Notifications#

Introduction#

Notifications Payload#

Notification Fields#

Payload Example#

Push Notifications#

Request#

Shipments#

Handling Units#

Response#

Successful#

Failed (4XX FAILED)#

Error (500 ERROR)#

Test Notifications#

Pull Notifications#

OAuth Request Format#

Response Format#

Successful#

Error response format#

Failed (4XX FAILED)#

Error (500 ERROR)#

Notifications Mapping#

Invalid Mappings Impact#

How to create or change a mapping#

Tracking Notifications

Introduction

Notifications Payload

Notification Fields

Payload Example

Push Notifications

Request

Shipments

Handling Units

Response

Successful

Failed (4XX FAILED)

Error (500 ERROR)

Test Notifications

Pull Notifications

OAuth Request Format

Response Format

Successful

Error response format

Failed (4XX FAILED)

Error (500 ERROR)

Notifications Mapping

Invalid Mappings Impact

How to create or change a mapping