International Authorization

Overview

This endpoint enables carriers to approve international shipments (between two countries). *** It interfaces with the carrier systems to verify that a package has been accepted and to retrieve tracking numbers. It handles the additional complexity of international shipping including customs, tariffs, CIF information, ***among others.

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
Future authorization of cancelled shipments: We should consider the possibility of a cancelled shipment being authorized again in the future.
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.

Consideraciones generales: identifica el flujo de integración entre sistemas.

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-3baa1164945",
7  "direction": "forward",
8  "test": false,
9  "carrier_information": { ... },
10  "shipment_information": { ... },
11  "authorization_information": { ... }
12 }'

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_information	Object	Items, dimensions, and package value	Always present in the request
international_information	Object	International-specific fields (customs, taxes, pickup address)	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
birthdate	String	Birthdate in format dd/MM/yyyy - for Uruguay	Optional
regime	String	Tax regime or business classification - for Uruguay	Optional

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

International Information

International-specific shipment details including customs, tariffs, and taxes:

Name	Data type	Description	Field presence in every request
tax_modality	String	Tax modality for international shipment.	Always present in the request
cif	Object	Cost, Insurance, Freight information	Always present in the request
destination_address	Object	Final delivery address in destination country	Always present in the request
pick_up_address	Object	International carrier pickup location	Always present in the request
drop_off_information	Object	Warehouse or drop-off details	Always present in the request
taxes	Object	Tax information including payer and amount	Always present in the request
exchange_rate	Decimal	Currency exchange rate if different currencies used	Always present in the request
remessa_conforme	Boolean	Remessa conforme status (Brazilian customs)	Always present in the request
sender_code_ece	String	Sender ECE code (customs exporter code)	Always present in the request
deliver_to	Object	Deliver-to information (importer details)	Always present in the request
receiver_email	String	Receiver's email address for customs notifications	Always present in the request
payments	Object	Payment information for international shipment	Always present in the request

CIF Object

Name	Data type	Description
cost	Decimal	Cost of goods (C in CIF). Example: 100.00
freight	Decimal	Freight/shipping cost (I in CIF). Example: 50.00
insurance	Decimal	Insurance cost (F in CIF). Example: 10.00

Pick-Up Address (International)

Field	Data type	Description
address_line	String	Full address line
zip_code	String	Postal code in origin country
city	Object	City information (id, name)
state	Object	State/province information (id, name)
country	Object	Country information (id, name)
phone	String	Contact phone number
additional_info	String	Additional instructions or notes

Drop-Off Information

Name	Data type	Description
warehouse_code	String	Warehouse or drop-off location code

Taxes Object

Name	Date type	Description
payer	Object	Tax payer information (name, identification, withholding flag)
total_amount	Decimal	Total tax amount due
detail	String	Tax detail/description

Payer Information

Name	Data type	Description
name	String	Payer full name
identification	Object	Payer identification (type, number)
apply_tax_withholding	Boolean	Whether to apply tax withholding

Deliver-To Information

Name	Data type	Description
full_name	String	Importer/final receiver full name
is_importer_final_receiver	Boolean	Whether importer is the final receiver

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": "Doce",
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        "international_information": {
101            "tax_modality": "taxModality",
102            "exchange_rate": 5.5,
103            "remessa_conforme": true,
104            "sender_code_ece": "senderCode",
105            "receiver_email": "receiver@email.com",
106            "cif": {
107                "cost": 20.0,
108                "freight": 10.0,
109                "insurance": 30.0
110            },
111            "destination_address": {
112                "street_name": "Street Name",
113                "street_number": "123",
114                "zip_code": "12345",
115                "city": {
116                    "id": "cityId",
117                    "name": "cityName"
118                },
119                "geolocation": {
120                    "geolocation_type": "ROOFTOP",
121                    "latitude": 10.0,
122                    "longitude": 20.0
123                }
124            },
125            "pick_up_address": {
126                "address_line": "Address Line",
127                "zip_code": "12345",
128                "city": {
129                    "id": "cityId",
130                    "name": "cityName"
131                },
132                "state": {
133                    "id": "cityId",
134                    "name": "cityName"
135                },
136                "country": {
137                    "id": "cityId",
138                    "name": "cityName"
139                },
140                "phone": "123456789",
141                "additional_info": "Additional Info"
142            },
143            "drop_off_information": {
144                "warehouse_code": "warehouseCode"
145            },
146            "deliver_to": {
147                "full_name": "Deliver To Full Name",
148                "is_importer_final_receiver": true
149            },
150            "taxes": {
151                "total_amount": 10.0,
152                "detail": {
153                    "tax1": 1,
154                    "tax2": 10
155                },
156                "payer": {
157                    "name": "Payer Name",
158                    "identification": {
159                        "type": "payerType",
160                        "number": "payerId"
161                    },
162                    "apply_tax_withholding": true
163                }
164            }
165        }
166    },
167    "test": false,
168    "keyword": "3bc405c30cadb4e6eefdf0cff899abcf8234d761c9a3ea1b2f510601ae5fc504"
169}

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 OK
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 OK
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.

International Authorization#

Overview#

Key Features#

HTTP Request#

Request Parameters#

Headers parameters#

Body Parameters#

Root level fields#

Carrier Information#

Agency Object#

#

Shipment Information#

Package Information#

International Information#

Requirements (Optional)#

Request Examples#

Successful Response (HTTP 200)#

Authorization information object#

#

Failed Response (HTTP 400)#

Error Response (HTTP 500)#

HTTP Status Codes & Errors#