Tracking Timeline#

Introduction#

This endpoint lists a shipment's tracking history. It was designed to meet legal requirements in which certain customs authorities must be notified in real time about the status of packages in international transit.

The response includes the shipment's tracking events.

Authentication#

Important: Security is handled via OAuth. You must include the access token in the Authorization: Bearer {accessToken} header on every request.

Request Format#

bashCopy
1GET 'https://api.mercadolibre.com/shipments/{shipmentId}/tracking/timeline'
2--header 'Authorization: Bearer {accessToken}'

Response Format#

The response body returns all tracking history data for the shipment:

Name	Data Type	Description
shipment_id	String	Unique shipment identifier (matches the route parameter).
timeline	Array	Ordered list of tracking events. May be empty if the shipment has no checkpoints.
timeline[].event_date	String (ISO 8601)	Event date and time. Examples: 2024-01-15T10:25:00Z or 2001-07-04T12:08:56.235-07:00.
timeline[].code	String	Event code.
timeline[].event_name	String (optional)	Normalized event name from the configuration catalog. Omitted from the JSON when null.

Examples#

Request#

bashCopy
1GET 'https://api.mercadolibre.com/shipments/1234567890/tracking/timeline'
2--header 'Authorization: Bearer {accessToken}'

Response#

Successful (HTTP 200) — with events#

jsonCopy
1{
2    "shipment_id": "1234567890",
3    "timeline": [
4        {
5            "event_date": "2025-11-16T17:00:00.000-04:00",
6            "code": "0201",
7            "event_name": "shipped"
8        }
9    ]
10}

Successful (HTTP 200) — no checkpoints#

jsonCopy
1{
2    "shipment_id": "1234567890",
3    "timeline": []
4}

Errors#

HTTP Code	Description
400	Invalid shipmentId format. Must be a positive numeric string.
401	Missing or invalid access token.
404	Shipment not found.
500	Internal server error or upstream service unavailable.

Error (HTTP 400)#

jsonCopy
1{
2    "message": "string",
3    "status": 400
4}

Error (HTTP 500)#

jsonCopy
1{
2    "message": "string",
3    "status": 500
4}