Domestic Auth

Overview

This endpoint enables carriers to approve domestic shipments (inside one country). It interfaces with the carrier systems to verify that a package has been accepted and to retrieve tracking numbers.

Key Features

Idempotency: Sending the same request twice returns the same tracking number
OAuth 2.0: Secure authentication with bearer tokens
Performance: Average response time under 1 second
Scalability: Handles high-volume shipment requests
Variable Data Length and Carrier Responsibility: Mercado Libre will send data fields with variable lengths, which may change over time. It is the carrier's responsibility to truncate this data as necessary to meet their specific storage requirements.

Mercado Libre is expected to receive a result, based on the "Status Code" section, that reflects whether the authorization was successful. If an error occurs, the system will automatically retry the communication following the retry schema established during the integration process.

Important: The Tracking Number of any shipment must only change on “n” authorizations if, and only if, a cancellation was previously requested.

HTTP Request

bash
1POST {url}/shipments/{shipment_id}/authorization
2 --header 'Content-Type: application/json'
3 --header 'Authorization: Bearer <access_token>'
4 --data-raw '{
5  "id": 2000005041469149431,
6  "transport_order_id": "ec4beec0-54d8-5066-a82d-3baa11649451",
7  "direction": "forward",
8  "test": false,
9  "carrier_information": { ... },
10  "shipment_information": { ... },
11  "authorization_information": { ... }
12 }'

Authentication

All requests require OAuth 2.0 Bearer token authentication. Include your access token in the Authorization header:

bash
1Authorization: Bearer YOUR_ACCESS_TOKEN

Request Parameters

Headers parameters

Name	Value	Description
Content-Type	application/json	Expected media type of the resource.
Authorization	Bearer <access_token>	Token generated (see OAuth 2.0 )

Body Parameters

Root level fields

These are the top-level fields in the authorization request:

Name	Data type	Description	Field presence in every request
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.	Always present in the request
transport_order_id	String	Unique identifier for the transport leg. This field is used to guarantee idempotency	Always present in the request
direction	String	Shipment direction. Values: forward (seller→buyer) or return (buyer→seller)	Optional
test	Boolean	Indicates that the request sent is for testing	Optional
keyword	String	The HASH (SHA256) of a secret word. The value of this parameter can be empty. If a value is present, the Carrier must request the secret word from the receiver of the package.	Conditional
carrier_information	Object	Carrier contract and agency information	Optional
shipment_information	Object	Sender, receiver, and package details	Optional
requirements	Object	Pickup and delivery requirements, among others	Conditional

Carrier Information

Carrier contract and agency details for the shipment:

Name	Data type	Description	Field presence in every request
contract	String	Identifies the contract / service defined by the carrier with which the shipment is to be authorized. For example, home delivery from XD, shipment to DS agency, etc.	Optional
agency	Object	Contains information related to the destination agency. Mandatory only when it is a shipment to a carrier agency.	Optional

Agency Object

Name	Data type	Description	Field presence in every request
id	String	Id given by Mercado Libre to the agency.	Optional

Shipment Information

Container object for sender, receiver, and package details:

Name	Type	Description	Field presence in every request
sender	Object	Shipment sender information (name, phone, address)	Always present in the request
receiver	Object	Shipment receiver information (name, phone, address)	Always present in the request
package	Object	Items, dimensions, and package value	Always present in the request

Sender & Receiver

Complete user information for both sender and receiver. All fields are set when the user object exists:

Name	Data type	Description	Field presence in every request
full_name	String	Full name or company name	Always present in the request
first_name	String	First name	Always present in the request
last_name	String	Last name	Always present in the request
phone	Object	Contact phone information (number)	Always present in the request
address	Object	Complete address details	Always present in the request

Phone Object

Name	Data type	Description	Field presence in every request
number	String	Phone number. Only numbers.	Always present in the request

Identification

Name	Data type	Description	Field presence in every request
type	String	User Identification Type (it may vary depending on the country)	Always present in the request
number	String	User identification number	Always present in the request

Address Fields

Complete address information for sender and receiver.

Field	Data type	Description	Field presence in every request
street_name	String	Street name. Example: Main Street	Optional
street_number	String	Street number. Example: 123	Optional
intersection	String	Secondary street, intersection or additional reference	Optional
address_line	String	Contains the street_name and street_number fields data	Always present in the request
comment	String	Special delivery instructions. Example: Ring bell 3 times	Optional
zip_code	String	Required in: Argentina, Brazil, Mexico, Peru. Optional in: Colombia, Uruguay, Chile, Ecuador	Always present in the request (for detailed countries)
city	Object	City localization (id, name)	Always present in the request
state	Object	State/Province localization (id, name)	Always present in the request
country	Object	Country localization (id, name)	Always present in the request
neighborhood	Object	Neighborhood/locality localization (id, name)	Optional
municipality	Object	Municipality localization (id, name)	Optional
geolocation	Object	Geographic coordinates (latitude, longitude, source)	Optional
facility_id	String	Facility identifier (for pickups or delivery at facilities)	Optional

Localization Object

Used for city, state, country, neighborhood, municipality:

Name	Data type	Description	Field presence in every request
id	String	Localization identifier provided by Mercado Libre. Format ISO 3166.	Optional
name	String	Localization name	Optional

Geolocation Object

Field	Type	Description	Field presence in every request
geolocation_type	String	It can be one of the following values: APPROXIMATE: approximate geolocation. GEOMETRIC_CENTER: locates the center of a region that is used as a reference. RANGE_INTERPOLATED: restricts precision to the midpoint of 2 nearby reference points. ROOFTOP: indicates that the location is exact. UNKNOWN: indicates that the location was not validated.	Always present in the request
latitude	Double	Geographic latitude in number format with 8 decimal places.	Always present in the request
longitude	Double	Geographic longitude in number format with 8 decimal places.	Always present in the request
source	String	Source of geolocation data	Always present in the request

Package Information

Details about the shipment package:

Name	Data type	Description	Field presence in every request
items	Array	Array of items in the package	Always present in the request
dimensions	Object	Package dimensions (height, width, length, weight)	Always present in the request
amount	Decimal	Package total value/amount. Example: 150.00	Always present in the request

Items

Individual items contained in the shipment package:

Field	Data type	Description	Field presence in every request
item_id	String	Unique item identifier on Mercadolibre	Always present in the request
description	String	Item description on Mercadlibre	Always present in the request
quantity	Long	Item quantity	Always present in the request

Dimensions

Package dimensions and weight specifications:

Name	Data type	Description	Unit	Field presence in every request
height	Decimal	Package height	Centimeters (cm)	Always present in the request
width	Decimal	Package width	Centimeters (cm)	Always present in the request
length	Decimal	Package length	Centimeters (cm)	Always present in the request
weight	Decimal	Total package weight	Grams (g)	Always present in the request
volumetric_weight	Decimal	Calculated volumetric weight (optional)	Grams (g)	Always present in the request

Requirements (Optional)

Additional shipment requirements (pickup and delivery schedules and special treatments):

Name	Date type	Description	Field presence in every request
special_treatments	Array	Array of special treatment codes (groupable, has_battery, special_goods, etc)	Optional
pickup	Object	Pickup schedule and location metadata requirements	Optional
delivery	Object	Delivery schedule, strategy, and location metadata requirements	Optional

Pickup Object

Name	Data type	Description
schedule	Object	Time window for pickup
location_metadata	Object	Location details and access information

Delivery Object

Field	Type	Description
schedule	Object	Time window for delivery
affinity_group	String	Delivery affinity group (for grouping deliveries together)
delivery_strategy	String	Operational strategy for delivery. E.g. "joint_delivery" (indicate that it must be delivered together with other shipments with the same affinity_group ).
location_metadata	Object	Location details and access information

Schedule Object

Field	Type	Description
from	DateTime	Window start time (ISO 8601 format)
to	DateTime	Window end time (ISO 8601 format)

Location Metadata Object

Field	Type	Description
location_id	String	Unique location identifier
has_reception	Boolean	Whether location has reception desk available
types	Array	Array of location types (residence, commercial, etc)
name	String	Location name or description
source	String	Source of location data
timetable	Object	Operating hours/timetable information
external_data	Object	External reference data (external_id, phone)
is_present	Boolean	Whether location is currently present/active

Note: Requirements are optional and only included under certain flows

Request Examples

Complete domestics shipment

json
1{
2    "id": "10101033319242",
3    "transport_order_id": "5c81e696e69190a58c13d4de71816b743",
4    "direction": "forward",
5    "carrier_information": {
6        "contract": "contract",
7        "agency": {
8          "id": "id"
9        } 
10    },
11    "shipment_information": {
12        "sender": {
13            "full_name": "John Doe",
14            "first_name": "John",
15            "last_name": "Doe",
16            "phone": {
17                "number": "123456789"
18            },
19            "address": {
20                "address_line": "Route 36 1234",
21                "street_name": "Route 36",
22                "street_number": "1234",
23                "intersection": "intersection",
24                "comment": "comment",
25                "city": {
26                    "id": "TUVDQ1BVRXJ0b3F1aQ",
27                    "name": "Puerto Quito"
28                },
29                "state": {
30                    "id": "EC-P",
31                    "name": "Pichincha"
32                },
33                "country": {
34                    "id": "EC",
35                    "name": "Ecuador"
36                },
37                "neighborhood": {
38                    "name": "Puerto Quito"
39                },
40                "municipality": {},
41                "geolocation": {
42                    "geolocation_type": "GEOMETRIC_CENTER",
43                    "latitude": -0.12345,
44                    "longitude": -78.123456
45                }
46            }
47        },
48        "receiver": {
49            "full_name": "John Doe",
50            "first_name": "John",
51            "last_name": "Doe",
52            "phone": {
53                "number": "123456789"
54            },
55            "address": {
56                "address_line": "Route 1 SN",
57                "street_name": "Route 1",
58                "street_number": "SN",
59                "intersection": "intersection",
60                "comment": "comment",
61                "city": {
62                    "id": "TUVDQ0VMWmMyZWRj",
63                    "name": "El Carmen"
64                },
65                "state": {
66                    "id": "EC-M",
67                    "name": "Manabí"
68                },
69                "country": {
70                    "id": "EC",
71                    "name": "Ecuador"
72                },
73                "neighborhood": {
74                    "name": "El Carmen"
75                },
76                "municipality": {},
77                "geolocation": {
78                    "geolocation_type": "GEOMETRIC_CENTER",
79                    "latitude": -0.123456,
80                    "longitude": -79.123456789
81                }
82            }
83        },
84        "package": {
85            "items": [
86                {
87                    "item_id": "MEC656877602",
88                    "description": "Lamp",
89                    "quantity": 1
90                }
91            ],
92            "dimensions": {
93                "height": 13,
94                "width": 26,
95                "length": 37,
96                "weight": 1100
97            },
98            "amount": 13.5
99        }
100    },
101    "test": false,
102    "keyword": "3bc405c30cadb4e6eefdf0cff899abcf8234d761c9a3ea1b2f510601ae5fc504"
103}

Response

Successful Response (HTTP 200)

bash
1HTTP 200 OK
2 --header 'Content-Type: application/json'
3 {
4    "id": "10101033319242",
5    "status":"AUTHORIZED",
6    "status_message":"OK",
7    "tracking_number": "ASDfgh123asd",
8    "authorization_information": {
9        "date": "2001-07-04T12:08:56.235-07:00",
10        "custom_data":{
11            "ruta_1":"RUTA"
12        }
13    }
14}

Name	Data type	Description	Mandatory
status	String	AUTHORIZED (when successful)	Mandatory
status_message	String	Descriptive message	Mandatory
tracking_number	String	Generated tracking number	Mandatory
authorization_information	Object	Authorization information	Mandatory

Authorization information object

Name	Data type	Description	Mandatory
date	Date (ISO 8601)	Authorization date	Mandatory
custom_data	Object	Custom data agreed during integration for labeling	Mandatory

Failed Response (HTTP 400)

bash
1HTTP 400 Bad Request
2 --header 'Content-Type: application/json'
3 {
4    "error_code": "invalid_user_information.buyer",
5    "status_message":"Missing receiver information",
6    "status": "FAILED"
7}

Error Response (HTTP 500)

bash
1HTTP 500 Internal Server Error
2 --header 'Content-Type: application/json'
3 {
4    "status_message":"Internal server error",
5    "status": "ERROR"
6}

HTTP Status Codes & Errors

HTTP	Status	Description
200	AUTHORIZED	Authentication with success.
400	FAILED	Whenever the request is invalid.
500	ERROR	Any authentication server issue.

Domestic Auth#

Overview#

Key Features#

HTTP Request#

Authentication#

Request Parameters#

Headers parameters#

Body Parameters#

Root level fields#

Carrier Information#

Agency Object#

Shipment Information#

Sender & Receiver#

Phone Object#

Identification#

Address Fields#

Localization Object#

Geolocation Object#

Package Information#

Items#

Dimensions#

Requirements (Optional)#

Pickup Object#

Delivery Object#

Schedule Object#

Location Metadata Object#

Request Examples#

Response#

Successful Response (HTTP 200)#

Authorization information object#

Failed Response (HTTP 400)#

Error Response (HTTP 500)#

HTTP Status Codes & Errors#