Design considerations

There are some things you should know about our API to make your life easier.


All responses are JSON encoded

JSON is a lightweight text-based open standard designed for human-readable data interchange. Our API supports and returns JSON by default.

We also return HTML responses when you’re surfing the API through a web browser. We use the Accept header to decide which response we return.

To overcome same origin policy, JSONP is also supported.

The same origin policy is an important security concept. To overcome it, we suggest using JSONP and CORS.


The API will respond JSONP if you provide a callback parameter. The value of this parameter will be used as the callback function. For example, doing:
$ curl
will return:
  "id": "ARS",
  "description": "Peso argentino",
  "symbol": "$",
  "decimal_places": 2,

For a JSONP response, add a callback parameter as follows:
$ curl
which will respond:
            "description":"Peso argentino",

As you can see, the response is an array with 3 values:
  • Http status code
  • Http response headers
  • Body of the response
All JSONP responses will always be 200 OK. This is in order to give you the chance to handle 30x, 40x, and 50x responses on the client side. The real response data is in the array.


Cross-origin resource sharing (CORS) is a web browser technology specification which defines ways for a web server to allow its resources to be accessed by a web page from a different domain. This is a way to overcome the same origin policy. All the APIs return a special header:
Access-Control-Allow-Origin: *
This allows the browser to access information provided by the API, even if it is from a different domain. All the major browsers have support for CORS. So basically this means that you don’t have to do anything and you get to access the API directly from your browser doing regular ajax calls with all the standard methods and avoiding things like JSONP.

All requests/responses are UTF-8 encoded

User: Are you really telling me that I can only use UTF-8 with MELI APIs? Us: Yes. User: Really? Us: Yes. User: Only? Us: Yes. We hope this has been enlightening for you. User: But, I must-- Us: Thank you, come again. User: But-- Us: Thank you, come again.

All dates are ISO 8601 encoded

We use ISO 8601 to encode dates in responses. Not all dates will use the same timezone. So dates will include the proper timezone.

All errors have a standard format

The standard format of an error is as follows:
  "message": "human readable text",
  "error": "machine_readable_error_code",
  "status": 400,
  "cause": [

Use selection to reduce the amount of returned attributes

In order to have smaller responses, with less data, you can add the attributes parameter with a comma separating the list of fields that should be included in the response. All the other fields of the original response will be ignored. This is supported only for array responses.
$ curl
    "id": "BRL"
    "id": "UYU"
    "id": "CLP"
This is supported only for array responses.

Filter by the IDs of resources

If you have a list of IDs of the resources you want to retrieve, you can avoid doing N calls to get them by just doing 1 call. This is done by adding the ids parameter to the query string.
$ curl,USD

API will provide documentation in JSON format using OPTIONS

There is a standard format to get API documentation. Use the OPTIONS http method to get a JSONencoded response that will describe the API with all the allowed methods and connections between another part of the API.
$ curl -X OPTIONS
    "description":"Devuelve información correspondiente al ISO de las monedas que se usan en MercadoLibre.",
    "attributes": {
        "id":"ID de la moneda (Código ISO)",
        "description":"Denominación oficial de la moneda",
        "symbol":"Símbolo ISO para representar la moneda",
        "decimal_places":"Número de decimales manejados con la moneda"
    "methods": [
            "description":"Devuelve el listado con todas las monedas."
            "description":"Devuelve información con respecto a una moneda específica."
    "connections": {

Next topic: Register your application

Be part of our community