Variations

Contents:

What is a variation?

A variation is a resource that allow sellers to set images and stock for each variant that a given same product may have. For example, in Fashion there may be pictures of each color or size within the same item publication. In Car parts, the same happens with right side, or left side in some accessories.

What are variations useful for?

  • The buyer can see inside same publication different versions and availability of the product.
  • Reduces Q&A between buyer and seller
  • Avoid negative ratings because the seller knows for sure what the purchased variation.
  • Reduce friction after-sales.
  • Allows a better control on items stock
  • Increases conversion

In addition, sellers can assign an SKU code for each variation. This will be very useful for those sellers who need to control their stock by inventory.

*NOTE: The price must be the same for every variation.

Next:
Standard variations.

Please rate this

Bookmarks

The Bookmarks feature explains itself, being a way to keep the items you’re interested associated to a user.
You can manage bookmarks through the Bookmarks API Resource, adding or removing references, which are synchronized with mobile apps.

Contents:

Get your bookmarks

Use the following url In order to retrieve your bookmarks:
Example:

curl -X GET https://api.mercadolibre.com/users/me/bookmarks?access_token=...

Response:

[
  ....
  {
	"bookmarked_date": "2012-07-20T10:22:04.736-04:00",
	"item_id": "MLA428108770",
  },
  {
	"bookmarked_date": "2012-07-17T16:46:46.079-04:00",
	"item_id": "MLA428424006",
  },
  {
	"bookmarked_date": "2012-07-13T16:41:43.937-04:00",
	"item_id": "MLA428112474",
  },
  ....
]

Bookmark an item

To bookmark an item, do as it follows:

Example:

curl -X POST -H "Content-Type: application/json" -d
'{
   	"item_id":"MLA5529"
 }'

"https://api.mercadolibre.com/users/me/bookmarks?access_token=$ACCESS_TOKEN"

Remove-a-bookmark

Bookmarks can be removed any time you want by simply deleting the reference.

Example:

curl -X DELETE "https://api.mercadolibre.com/users/me/bookmarks/MLA605670642?access_token=$ACCESS_TOKEN"



Next topic: Check account balance.

Please rate this

User’s addresses

The purpose of the following document is to introduce the Address API, specifying the fields listed in the response to your query, along with the potential responses to those fields.

Contents:

Get user’s addresses

To make a call to this API, you will need an access token.

Example:

curl -X GET https://api.mercadolibre.com/users/{User_id}/addresses?access_token=$ACCESS_TOKEN

Response:

{
	"id": 145834937,
	"user_id": "160252486",
	"contact": null,
	"phone": null,
	"address_line": "Guatemala 5100",
	"floor": null,
	"apartment": null,
	"street_number": "5100",
	"street_name": "Guatemala",
	"zip_code": "1000",
	"city": -{
    	"id": "TUxBQlBBTDI1MTVa",
    	"name": "Palermo",
	},
	"state": -{
    	"id": "AR-C",
    	"name": "Capital Federal",
    	
	},
	"country": -{
    	"id": "AR",
    	"name": "Argentina",
	},
	"neighborhood": -{
    	"id": null,
    	"name": null,
	},
	"municipality": -{
    	"id": null,
    	"name": null,
	},
	"search_location": -{
    	"state": -{
        	"id": "TUxBUENBUGw3M2E1",
        	"name": "Capital Federal",
    	},
    	"city": -{
        	"id": "TUxBQ0NBUGZlZG1sYQ",
        	"name": "Capital Federal",
    	},
    	"neighborhood": -{
        	"id": "TUxBQlBBTDI1MTVa",
        	"name": "Palermo",
    	},
	},
	"types": -[
        "default_selling_address",
    	"shipping",
	],
	"comment": "",
	"geolocation_type": "RANGE_INTERPOLATED",
	"latitude": -34.5834729,
	"longitude": -58.4281022,
	"status": "active",
	"date_created": "2014-06-05T12:26:54.000-04:00",
	"normalized": true,
	"open_hours": -{
    	"on_holidays": -{
        	"hours": [
        	],
        	"status": "closed",
    	},
	},
}

Response fields description

FieldSub-fieldDescription
idRequested address ID
user_idUser ID
contactName of the information owner (user)
phoneUser’s telephone number
address_lineUser’s full address (street and number)
floorBuilding floor, if the address belongs to an apartment
apartmentApartment identification (number or letter)
street_numberStreet number of the address mentioned in “address_line”
street_nameStreet name of the address mentioned in “address_line”
zip_codeZip code
cityCity where the address is located
idUnique city identifier (locations API core)
nameName of the city
stateState/province where the city is located.
idUnique city state/province identifier (locations API core)
nameName of the state/province
countryCountry where the address is located
idUnique city country identifier (locations API core)
nameName of the country
neighborhoodNeighborhood associated to the address
idUnique neighborhood identifier.
nameName of the neighborhood
municipalityMunicipality associated to the address
idUnique municipality identifier
nameName of the municipality
search_locationInformation about the address to be used in search lists.
stateState/province where the city is located as per Classified.  The ID is associated to the classified locations API.
cityCity where the address is located, as per Classified. The ID is associated to the classified locations API.
neighbourhoodNeighborhood where the address is located as per Classified. The ID is associated to the classified locations API.
typesIt specifies the address type: Possible values:

● default_selling_address: selling address

● default_buying_address: buying address

● shipping: address from which shipments will be made

● billing: MercadoLibre billing address.

Types may include none, one, or several of the above attributes.

commentComments on the address information.
geolocation_typeApproximate range of the address in question, based on Google Maps’ latitude and longitude parameters.
latitudeGoogle Maps latitude.
longitudeGoogle Maps longitude.
statusAddress status. Possible values: active or inactive.
date_createdDate and time when it was created.
normalizedIt indicates if the stored data is correct. If not, it will be false. Possible values: true, false.
open_hoursBusiness hours, if the address belongs to a store.
on_holidaysSpecial business hours on holidays. Sub-attribute hours included.

Next topic: Add and manage user’s bookmarks.

Please rate this

Shipping status and substatus

To get a description of all possible shipping status and it’s substatus you can make a call to our shipment_statuses resource.

Example:

curl -X GET https://api.mercadolibre.com/shipment_statuses

Response:

{
    "id": "to_be_agreed",
    "name": "To be agreed",
    "substatuses": [
    ]
  },
  {
    "id": "pending",
    "name": "Pending",
    "substatuses": [
      {
        "id": "cost_exceeded",
        "name": "Cost exceeded"
      }
    ]
  },
  {
    "id": "handling",
    "name": "Handling",
    "substatuses": [
      {
        "id": "regenerating",
        "name": "Regenerating"
      },
      {
        "id": "waiting_for_label_generation",
        "name": "Waiting for label generation"
      }
    ]
  },
  {
    "id": "ready_to_ship",
    "name": "Ready to ship",
    "substatuses": [
      {
        "id": "ready_to_print",
        "name": "Ready to print"
      },
      {
        "id": "invoice_pending",
        "name": "Invoice pending"
      },
      {
        "id": "printed",
        "name": "Printed"
      },
      {
        "id": "in_pickup_list",
        "name": "In pikcup list"
      },
      {
        "id": "ready_for_pkl_creation",
        "name": "Ready for pkl creation"
      },
      {
        "id": "ready_for_pickup",
        "name": "Ready for pickup"
      },
      {
        "id": "picked_up",
        "name": "Picked up"
      },
      {
        "id": "stale",
        "name": "Stale Ready To Ship"
      },
      {
        "id": "in_hub",
        "name": "In hub"
      },
      {
        "id": "measures_ready",
        "name": "Measures and weight ready"
      },
      {
        "id": "waiting_for_carrier_authorization",
        "name": "Waiting for carrier authorization"
      },
      {
        "id": "authorized_by_carrier",
        "name": "Authorized by carrier"
      },
      {
        "id": "in_plp",
        "name": "In PLP"
      }
    ]
  },
  {
    "id": "shipped",
    "name": "Shipped",
    "substatuses": [
      {
        "id": "delayed",
        "name": "Delayed"
      },
      {
        "id": "waiting_for_withdrawal",
        "name": "Waiting for withdrawal"
      },
      {
        "id": "contact_with_carrier_required",
        "name": "Contact with carrier required"
      },
      {
        "id": "receiver_absent",
        "name": "Receiver absent"
      },
      {
        "id": "reclaimed",
        "name": "Reclaimed"
      },
      {
        "id": "not_localized",
        "name": "Not localized"
      },
      {
        "id": "forwarded_to_third",
        "name": "Forwarded to third party"
      },
      {
        "id": "soon_deliver",
        "name": "Soon deliver"
      },
      {
        "id": "refused_delivery",
        "name": "Delivery refused"
      },
      {
        "id": "bad_address",
        "name": "Bad address"
      },
      {
        "id": "negative_feedback",
        "name": "Stale shipped with negative feedback by buyer"
      },
      {
        "id": "need_review",
        "name": "Need to review carrier status to understand what happened"
      },
      {
        "id": "stale",
        "name": "Stale shipped"
      }
    ]
  },
  {
    "id": "delivered",
    "name": "Delivered",
    "substatuses": [
      {
        "id": "damaged",
        "name": "damaged"
      },
      {
        "id": "fulfilled_feedback",
        "name": "Fulfilled by buyer feedback"
      },
      {
        "id": "no_action_taken",
        "name": "No action taken by buyer"
      },
      {
        "id": "double_refund",
        "name": "Double Refund"
      }
    ]
  },
  {
    "id": "not_delivered",
    "name": "Not delivered",
    "substatuses": [
      {
        "id": "returning_to_sender",
        "name": "Returning to sender"
      },
      {
        "id": "retained",
        "name": "Retained"
      },
      {
        "id": "stolen",
        "name": "Stolen"
      },
      {
        "id": "returned",
        "name": "Returned"
      },
      {
        "id": "receiver_absent",
        "name": "Receiver absent"
      },
      {
        "id": "confiscated",
        "name": "confiscated"
      },
      {
        "id": "to_review",
        "name": "Closed shipment"
      },
      {
        "id": "destroyed",
        "name": "Destroyed"
      },
      {
        "id": "waiting_for_withdrawal",
        "name": "Waiting for withdrawal"
      },
      {
        "id": "negative_feedback",
        "name": "Stale shipped forced to not delivered due to negative feedback by buyer"
      },
      {
        "id": "claimed_me",
        "name": "Stale shipped with claim that was forced to not delivered"
      },
      {
        "id": "not_localized",
        "name": "Not localized"
      },
      {
        "id": "double_refund",
        "name": "Double Refund"
      }
    ]
  },
  {
    "id": "not_verified",
    "name": "Not verified",
    "substatuses": [
    ]
  },
  {
    "id": "cancelled",
    "name": "Cancelled",
    "substatuses": [
    ]
  },
  {
    "id": "closed",
    "name": "Closed",
    "substatuses": [
    ]
  },
  {
    "id": "error",
    "name": "Error",
    "substatuses": [
    ]
  },
  {
    "id": "active",
    "name": "Active",
    "substatuses": [
    ]
  },
  {
    "id": "not_specified",
    "name": "Not specified",
    "substatuses": [
    ]
  },
  {
    "id": "stale_ready_to_ship",
    "name": "Stale ready to ship",
    "substatuses": [
    ]
  },
  {
    "id": "stale_shipped",
    "name": "Stale shipped",
    "substatuses": [
    ]
  }


Please rate this

Calculate shipping costs & handling time

On our Marketplace sellers will have a shipping calculator on the item description page so buyers will know the cost for the shipping and estimated handling time.
You can use our resources to calculate this basing on the information you have.

Contents:

Attributes description

Let’s see a quick description of each attribute you’ll find on our calculator resource.

destination
Receiver address details.
Attributes
zip_code
Destination zip code.
city
Destination city info.
Attributes
id
Destination city id.
name
Destination city name.
state
Destination state info.
Attributes
id
Destination state id.
name
Destination state name.
country
Destination country info.
Attributes
id
Destination country id.
name
Destination country name.
extended_attributes
Destination address additional info.
Attributes
address
Destination address line.
owner_name
Destination address owner.
zip_code_type
Destination zip code type info.
Attributes
type
Destination zip code type id.
description
Destination zip code type name.
city_type
Destination city type id.
city_name
Destination city name.
version
Internal version of this data in Zipcodes API.
options
Collection of shipping costs for each available shipping method.
Attributes
id
Id of applied shipping rule.
name
Shipping method name.
currency_id
Id of currency used to show shipping costs.
list_cost
Real shipping costs, no free shipping applied.
cost
Final shipping cost, free shipping could apply.
tracks_shipments_status
Indicates how this method may be tracked
Attributes
verified
Can be internally tracked.
not_verified
Tracking information must be provided by seller.
no
Cannot be tracked.
display
Shipping method id for frontend processing.
Attributes
always
Shipping method must be displayed.
optional
Method may not be displayed because there exists a faster and cheaper one.
speed
Delivery speed info.
Attributes
shipping
Average hours for delivery itself.
handling
Average hours for shipment to be shipped by seller.

 

Calculate over zip code and item dimensions

Example:

curl -X GET https://api.mercadolibre.com/sites/MLB/shipping_options?zip_code_from=01310909&zip_code_to=01310909&dimensions=16x16x16,1500

Response:

{
  "destination": {
    "zip_code": "01310909",
    "city": {
      "id": "BR-SP-44",
      "name": "São Paulo"
    },
    "state": {
      "id": "BR-SP",
      "name": "São Paulo"
    },
    "country": {
      "id": "BR",
      "name": "Brasil"
    },
    "extended_attributes": {
      "address": "Avenida Paulista, 688",
      "owner_name": "Edifício Santa Filippa",
      "zip_code_type": {
        "type": "LO",
        "description": "Logradouro"
      },
      "city_type": "CI",
      "city_name": "São Paulo",
      "neighborhood": "Bela Vista",
      "status": "active"
    }
  },
  "options": [
    {
      "id": 27554373,
      "name": "Normal",
      "shipping_method_id": 100009,
      "currency_id": "BRL",
      "list_cost": 9.66,
      "cost": 9.66,
      "tracks_shipments_status": "not_verified",
      "display": "recommended",
      "speed": {
        "shipping": 96,
        "handling": 48
      },
      "estimated_delivery": {
        "date": "2016-02-26T00:00:00.000-02:00",
        "pay_before": null,
        "time_from": null,
        "time_to": null
      },
      "estimated_delivery_time": {
        "type": "known_frame",
        "date": "2016-02-24T00:00:00.000-02:00",
        "shipping": 48,
        "handling": 48,
        "unit": "hour",
        "offset": {
          "date": "2016-02-26T00:00:00.000-02:00",
          "shipping": 48
        },
        "time_frame": {
          "from": null,
          "to": null
        },
        "pay_before": null
      },
      "discount": {
        "rate": 0,
        "type": "none",
        "promoted_amount": 0
      }
    },
    {
      "id": 27551043,
      "name": "Expresso",
      "shipping_method_id": 182,
      "currency_id": "BRL",
      "list_cost": 9.83,
      "cost": 9.83,
      "tracks_shipments_status": "not_verified",
      "display": "always",
      "speed": {
        "shipping": 48,
        "handling": 48
      },
      "estimated_delivery": {
        "date": "2016-02-24T00:00:00.000-02:00",
        "pay_before": null,
        "time_from": null,
        "time_to": null
      },
      "estimated_delivery_time": {
        "type": "known_frame",
        "date": "2016-02-23T00:00:00.000-02:00",
        "shipping": 24,
        "handling": 48,
        "unit": "hour",
        "offset": {
          "date": "2016-02-24T00:00:00.000-02:00",
          "shipping": 24
        },
        "time_frame": {
          "from": null,
          "to": null
        },
        "pay_before": null
      },
      "discount": {
        "rate": 0,
        "type": "none",
        "promoted_amount": 0
      }
    }
  ]
}

 

Calculate over user & zip code

Example:

curl -X GET https://api.mercadolibre.com/users/190990642/shipping_options?zip_code=01310909&dimensions=16x16x16,1500

Response:

{
  "destination": {
    "zip_code": "01310909",
    "city": {
      "id": "BR-SP-44",
      "name": "São Paulo"
    },
    "state": {
      "id": "BR-SP",
      "name": "São Paulo"
    },
    "country": {
      "id": "BR",
      "name": "Brasil"
    },
    "extended_attributes": {
      "address": "Avenida Paulista, 688",
      "owner_name": "Edifício Santa Filippa",
      "zip_code_type": {
        "type": "LO",
        "description": "Logradouro"
      },
      "city_type": "CI",
      "city_name": "São Paulo",
      "neighborhood": "Bela Vista",
      "status": "active"
    }
  },
  "options": [
    {
      "id": 27555383,
      "name": "Normal",
      "shipping_method_id": 100009,
      "currency_id": "BRL",
      "list_cost": 11.86,
      "cost": 11.86,
      "tracks_shipments_status": "not_verified",
      "display": "recommended",
      "speed": {
        "shipping": 96,
        "handling": 48
      },
      "estimated_delivery": {
        "date": "2016-03-01T00:00:00.000-02:00",
        "pay_before": null,
        "time_from": null,
        "time_to": null
      },
      "estimated_delivery_time": {
        "type": "known_frame",
        "date": "2016-02-26T00:00:00.000-02:00",
        "shipping": 48,
        "handling": 48,
        "unit": "hour",
        "offset": {
          "date": "2016-03-01T00:00:00.000-02:00",
          "shipping": 48
        },
        "time_frame": {
          "from": null,
          "to": null
        },
        "pay_before": null
      },
      "discount": {
        "rate": 0,
        "type": "none",
        "promoted_amount": 0
      }
    },
    {
      "id": 27843879,
      "name": "Expresso",
      "shipping_method_id": 182,
      "currency_id": "BRL",
      "list_cost": 16.48,
      "cost": 16.48,
      "tracks_shipments_status": "not_verified",
      "display": "always",
      "speed": {
        "shipping": 48,
        "handling": 48
      },
      "estimated_delivery": {
        "date": "2016-02-26T00:00:00.000-02:00",
        "pay_before": null,
        "time_from": null,
        "time_to": null
      },
      "estimated_delivery_time": {
        "type": "known_frame",
        "date": "2016-02-25T00:00:00.000-02:00",
        "shipping": 24,
        "handling": 48,
        "unit": "hour",
        "offset": {
          "date": "2016-02-26T00:00:00.000-02:00",
          "shipping": 24
        },
        "time_frame": {
          "from": null,
          "to": null
        },
        "pay_before": null
      },
      "discount": {
        "rate": 0,
        "type": "none",
        "promoted_amount": 0
      }
    }
  ]
}

 

Calculate over city on MCO

You can calculate shipping costs for a given site. On MCO is different from other sites since you the calculation is done over city_from, city_to and dimensions parameters. As you can see in the following example, this resource allows multi-get. You need to link the city codes one by one.
Example:

curl -X GET https://api.mercadolibre.com/sites/MCO/shipping_options?city_from=Q08tRENCb2dvdA&city_to=TUNPQ0NBUjcwNTYz,TUNPQ01FRGRjNjc4&dimensions=10x10x10,1000

Response:

{
  "TUNPQ01FRGRjNjc4": {
    "destination": {
      "zip_code": null,
      "city": {
        "id": "TUNPQ01FRGRjNjc4",
        "name": "Medellín"
      },
      "state": {
        "id": "CO-ANT",
        "name": "Antioquia"
      },
      "country": {
        "id": "CO",
        "name": "Colombia"
      }
    },
    "options": [
      {
        "id": 523836053,
        "name": "Servientrega Normal",
        "shipping_method_id": 501745,
        "currency_id": "COP",
        "list_cost": 7500,
        "cost": 7500,
        "tracks_shipments_status": "not_verified",
        "display": "recommended",
        "speed": {
          "shipping": 24,
          "handling": 72
        },
        "estimated_delivery": {
          "date": "2016-02-26T00:00:00.000-05:00",
          "pay_before": null,
          "time_from": null,
          "time_to": null
        },
        "estimated_delivery_time": {
          "type": "known",
          "date": "2016-02-26T00:00:00.000-05:00",
          "shipping": 24,
          "handling": 72,
          "unit": "hour",
          "offset": {
            "date": null,
            "shipping": null
          },
          "time_frame": {
            "from": null,
            "to": null
          },
          "pay_before": null
        },
        "discount": {
          "rate": 0,
          "type": "none",
          "promoted_amount": 0
        }
      }
    ]
  },
  "TUNPQ0NBUjcwNTYz": {
    "destination": {
      "zip_code": null,
      "city": {
        "id": "TUNPQ0NBUjcwNTYz",
        "name": "Cartagena De Indias"
      },
      "state": {
        "id": "CO-BOL",
        "name": "Bolivar"
      },
      "country": {
        "id": "CO",
        "name": "Colombia"
      }
    },
    "options": [
      {
        "id": 523835977,
        "name": "Servientrega Normal",
        "shipping_method_id": 501745,
        "currency_id": "COP",
        "list_cost": 7500,
        "cost": 7500,
        "tracks_shipments_status": "not_verified",
        "display": "recommended",
        "speed": {
          "shipping": 48,
          "handling": 72
        },
        "estimated_delivery": {
          "date": "2016-02-29T00:00:00.000-05:00",
          "pay_before": null,
          "time_from": null,
          "time_to": null
        },
        "estimated_delivery_time": {
          "type": "known",
          "date": "2016-02-29T00:00:00.000-05:00",
          "shipping": 48,
          "handling": 72,
          "unit": "hour",
          "offset": {
            "date": null,
            "shipping": null
          },
          "time_frame": {
            "from": null,
            "to": null
          },
          "pay_before": null
        },
        "discount": {
          "rate": 0,
          "type": "none",
          "promoted_amount": 0
        }
      }
    ]
  }
}

 

Shipping costs by User, city and dimensions on MCO

If you want, you can calculate the shipping costs for an specific user to a given city and dimensions. As you can see in the following example, this resource allows multi-get. You need to concatenate the city codes one by one.
Example:

GET https://api.mercadolibre.com/users/454271894/shipping_options?city_to=Q08tRENCb2dvdA,TUNPQ01FRGRjNjc4&dimensions=15x15x15,650

Response:

{
    "destination": {
        "zip_code": null,
        "city": {
            "id": "Q08tRENCb2dvdA",
            "name": "Bogotá"
        },
        "state": {
            "id": "CO-DC",
            "name": "Bogota D.C."
        },
        "country": {
            "id": "CO",
            "name": "Colombia"
        }
    },
    "options": [
        {
            "id": 11110,
            "name": "Servientrega Estandar",
            "shipping_method_id": 501745,
            "currency_id": "COP",
            "list_cost": 7.5,
            "cost": 7.5,
            "tracks_shipments_status": "verified",
            "display": "recommended",
            "speed": {
                "shipping": 48,
                "handling": null
            },
            "estimated_delivery": {
                "date": null,
                "pay_before": null,
                "time_from": null,
                "time_to": null
            },
            "discount": {
                "rate": 0
            }
        }
    ],
    "settings": {
        "allow_add_cost": null
    }
}

 

Shipping costs over Item and city on MCO

Calculate shipping costs for an Item sending only the Item_id and City_to parameters.
Example:

GET https://api.mercadolibre.com/items/MCO415774919/shipping_options?city_to=Q08tRENCb2dvdA

Response:

{
  "destination": {
    "zip_code": null,
    "city": {
      "id": "Q08tRENCb2dvdA",
      "name": "Bogotá"
    },
    "state": {
      "id": "CO-DC",
      "name": "Bogota D.C."
    },
    "country": {
      "id": "CO",
      "name": "Colombia"
    }
  },
  "options": [
    {
      "id": 523835933,
      "name": "Servientrega Normal",
      "shipping_method_id": 501745,
      "currency_id": "COP",
      "list_cost": 5000,
      "cost": 0,
      "tracks_shipments_status": "verified",
      "display": "recommended",
      "speed": {
        "shipping": 24,
        "handling": 72
      },
      "estimated_delivery": {
        "date": "2015-06-22T00:00:00.000-05:00",
        "pay_before": null,
        "time_from": null,
        "time_to": null
      },
      "discount": {
        "rate": 0,
        "type": "none",
        "promoted_amount": 0
      }
    }
  ]
}

 

Brief description of the attributes

AttributesJSON Response

"estimated_delivery_time": {
    "type": "known|known_frame|unknown_frame",
    "date": 2015-09-10T00: 00: 00: 000-03: 00",
"shipping": 72,
"handling": 24,
"unit": "hour",
"offset": {
    "date": null,
    "shipping": null
},
"time_frame": {
    "from": "12: 00",
    "to": "15: 00"
},
"pay_before": null
}

Delivery promise type

known: Exact date and handling time known.

...
...
 "estimated_delivery_time": {
        "type": "known",
        "date": "2015-09-10T00:00:00:000-03:00",
        "shipping": 72,
        "handling": 24,
        "unit": "hour",
        "offset": {
          "date": null,
          "shipping": null
        },
        "time_frame": {
          "from":"12:00",
          "to": "15:00"
        },
        "pay_before": null
      },
      …

1

Unknown: Exact date and handling time unknown.

...
...
 "estimated_delivery_time": {
        "type": "unknown",
        "date": null,
        "shipping": 72,
        "handling": null,
        "unit": "hour",
        "offset": {
          "date": null,
          "shipping": null
        },
        "time_frame": {
          "from":"null",
          "to": "null"
        },
        "pay_before": null
      },
      …

3

known_frame: Specific date and handling time known.

...
...
 "estimated_delivery_time": {
        "type": "known_frame",
        "date": "2015-09-10T00:00:00:000-03:00",
        "shipping": 72,
        "handling": 24,
        "unit": "hour",
        "offset": {
          "date": "2015-09-12T00:00:00:000-03:00",
          "shipping": 48
        },
        "time_frame": {
          "from":"12:00",
          "to": "15:00"
        },
        "pay_before": null
      },
      ...

2

unknown_frame: Business days range and handling time unknown.

...
...
 "estimated_delivery_time": {
        "type": "unknown_frame",
        "date": "null",
        "shipping": 72,
        "handling": null,
        "unit": "hour",
        "offset": {
          "date": "null",
          "shipping": 48
        },
        "time_frame": {
          "from":"null",
          "to": "null"
        },
        "pay_before": null
      },
      ...

4

Considerations

  • Business days range defined by the limits [“shipping”, “shipping” + “offset.shipping”].
  • Delivery dates (“date” and “offset.date”) exist if the handling time is know.
  • “time_frame” applies only to carriers that handle well-defined frames.
  • “pay_before” only applies to carriers that handle well-defined frames.
  • These changes will be reflected at GET /shipments/$ID, GET /orders/$ID/shipments and GET /orders/$ID.

Please rate this

Custom Variations

Contents:

What are custom variations?

When users do not find the attributes they need for a certain variation, they will be able to create a “custom variation” that better fits or describe their products.
For example, a cell-phones covers seller need to add the “design” attribute for a variation. Doing so, he will be able to create 1 listing with the different design variations.

customvariations

Using custom variations

When using custom variations, make sure the category in which you want to list products has attributes. Also, attributes and existing values in that category are different to which you are intending to add. Take into account that only is possible to add one type of variation per product.

Listing products with custom variations

First of all, you need to check on the Categories API if the selected category accepts the type of variation you are intending to add:
Call:

curl -X GET https://api.mercadolibre.com/categories/{Category_id}

Example:

curl -X GET https://api.mercadolibre.com/categories/MLA70400

Response:

{
  "id": "MLA70400",
  "name": "Silicona",
  "picture": null,
  "permalink": null,
  "total_items_in_this_category": 1693,
  "path_from_root": [
    {
      "id": "MLA1051",
      "name": "Celulares y Teléfonos"
    },
    {
      "id": "MLA3502",
      "name": "Accesorios para Celulares"
    },
    {
      "id": "MLA5337",
      "name": "Holders y Fundas"
    },
    {
      "id": "MLA39387",
      "name": "iPhone"
    },
    {
      "id": "MLA70400",
      "name": "Silicona"
    }
  ],
  "children_categories": [
  ],
  "attribute_types": "none",
  "settings": {
    "adult_content": false,
    "buying_allowed": true,
    "buying_modes": [
      "auction",
      "buy_it_now"
    ],
    "coverage_areas": "not_allowed",
    "currencies": [
      "ARS"
    ],
    "fragile": false,
    "immediate_payment": "optional",
    "item_conditions": [
      "used",
      "new",
      "not_specified"
    ],
    "items_reviews_allowed": false,
    "max_description_length": 50000,
    "max_pictures_per_item": 12,
    "max_sub_title_length": 70,
    "max_title_length": 60,
    "price": "required",
    "restrictions": [
    ],
    "rounded_address": false,
    "seller_contact": "not_allowed",
    "shipping_modes": [
      "me1",
      "me2",
      "not_specified",
      "custom"
    ],
    "shipping_options": [
      "custom",
      "carrier"
    ],
    "shipping_profile": "optional",
    "show_contact_information": false,
    "simple_shipping": "optional",
    "stock": "required",
    "tags": [
    ],
    "vip_subdomain": "articulo",
    "mirror_category": null,
    "listing_allowed": true,
    "maximum_price": null,
    "minimum_price": null
  },
  "meta_categ_id": 22340,
  "attributable": false
}



The next step is to perform a call to the attributes resource to find out if the category has fixed attributes.

curl -X GET https://api.mercadolibre.com/categories/{Category_id}/attributes

Example:

curl -X GET https://api.mercadolibre.com/categories/MLA90105/attributes



In this case, the category does not have attributes, therefore the variation will be added under no restrictions. You can encode your Json as the following example.
Example:

curl -XPOST -H "Content-type: application/json" -d '{
    "site_id": "MLA",
    "title": "Item de Test - No Ofertar",
    "category_id": "MLA70400",
    "price": 1000,
    "currency_id": "ARS",
    "available_quantity": 9,
    "buying_mode": "buy_it_now",
    "listing_type_id": "bronze",
    "condition": "new",
    "video_id": null,
    "description": "item de test",
    "variations": [
        {
            "price": 1000,
            "available_quantity": 3,
            "picture_ids": [
                "21150-MLA20204290696_112014"
            ],
            "attribute_combinations": [
                {
                    "name": "Diseño",
                    "value_name": "Bulldog"
                }
            ]
        },
        {
            "price": 1000,
            "available_quantity": 3,
            "picture_ids": [
                "21124-MLA20204291671_112014"
            ],
            "attribute_combinations": [
                {
                    "name": "Diseño",
                    "value_name": "Búho"
                }
            ]
        }
    ]
}' https://api.mercadolibre.com/items?access_token={$ACCESS_TOKEN}

Response:

{  
   "id":"MLA601053403",
   "site_id":"MLA",
   "title":"Item De Test - No Ofertar",
   "subtitle":null,
   "seller_id":202593498,
   "category_id":"MLA70400",
   "official_store_id":null,
   "price":1000,
   "base_price":1000,
   "original_price":null,
   "currency_id":"ARS",
   "initial_quantity":6,
   "available_quantity":6,
   "sold_quantity":0,
   "buying_mode":"buy_it_now",
   "listing_type_id":"bronze",
   "start_time":"2016-01-18T18:01:14.422Z",
   "stop_time":"2016-03-18T18:01:14.422Z",
   "end_time":"2016-03-18T18:01:14.422Z",
   "condition":"new",
   "permalink":"http://articulo.mercadolibre.com.ar/MLA-601053403-item-de-test-no-ofertar-_JM",
   "thumbnail":"http://mla-s1-p.mlstatic.com/21150-MLA20204290696_112014-I.jpg",
   "secure_thumbnail":"https://a248.e.akamai.net/mla-s1-p.mlstatic.com/21150-MLA20204290696_112014-I.jpg",
   "pictures":[  
      {  
         "id":"21150-MLA20204290696_112014",
         "url":"http://mla-s1-p.mlstatic.com/21150-MLA20204290696_112014-O.jpg",
         "secure_url":"https://a248.e.akamai.net/mla-s1-p.mlstatic.com/21150-MLA20204290696_112014-O.jpg",
         "size":"281x500",
         "max_size":"336x596",
         "quality":""
      },
      {  
         "id":"21124-MLA20204291671_112014",
         "url":"http://mla-s1-p.mlstatic.com/21124-MLA20204291671_112014-O.jpg",
         "secure_url":"https://a248.e.akamai.net/mla-s1-p.mlstatic.com/21124-MLA20204291671_112014-O.jpg",
         "size":"500x500",
         "max_size":"700x700",
         "quality":""
      }
   ],
   "video_id":null,
   "descriptions":[  
      {  
         "id":"MLA601053403-1011616345"
      }
   ],
   "accepts_mercadopago":true,
   "non_mercado_pago_payment_methods":[  

   ],
   "shipping":{  
      "mode":"not_specified",
      "local_pick_up":false,
      "free_shipping":false,
      "methods":[  

      ],
      "dimensions":null,
      "tags":[  

      ]
   },
   "international_delivery_mode":"none",
   "seller_address":{  
      "id":175597910,
      "comment":"",
      "address_line":"Test Address 123",
      "zip_code":"1414",
      "city":{  
         "id":"",
         "name":"Palermo"
      },
      "state":{  
         "id":"AR-C",
         "name":"Capital Federal"
      },
      "country":{  
         "id":"AR",
         "name":"Argentina"
      },
      "latitude":-34.5711496,
      "longitude":-58.4232966,
      "search_location":{  
         "neighborhood":{  
            "id":"",
            "name":""
         },
         "city":{  
            "id":"TUxBQ0NBUGZlZG1sYQ",
            "name":"Capital Federal"
         },
         "state":{  
            "id":"TUxBUENBUGw3M2E1",
            "name":"Capital Federal"
         }
      }
   },
   "seller_contact":null,
   "location":{  

   },
   "geolocation":{  
      "latitude":-34.5711496,
      "longitude":-58.4232966
   },
   "coverage_areas":[  

   ],
   "attributes":[  

   ],
   "warnings":[  

   ],
   "listing_source":"",
   "variations":[  
      {  
         "id":10541993184,
         "attribute_combinations":[  
            {  
               "id":null,
               "name":"Diseño",
               "value_id":null,
               "value_name":"Bulldog"
            }
         ],
         "price":1000,
         "available_quantity":3,
         "sold_quantity":0,
         "picture_ids":[  
            "21150-MLA20204290696_112014"
         ],
         "seller_custom_field":null,
         "attributes":[  

         ]
      },
      {  
         "id":10541993186,
         "attribute_combinations":[  
            {  
               "id":null,
               "name":"Diseño",
               "value_id":null,
               "value_name":"Búho"
            }
         ],
         "price":1000,
         "available_quantity":3,
         "sold_quantity":0,
         "picture_ids":[  
            "21124-MLA20204291671_112014"
         ],
         "seller_custom_field":null,
         "attributes":[  

         ]
      }
   ],
   "status":"not_yet_active",
   "sub_status":[  

   ],
   "tags":[  

   ],
   "warranty":null,
   "catalog_product_id":null,
   "seller_custom_field":null,
   "parent_item_id":null,
   "differential_pricing":null,
   "deal_ids":[  

   ],
   "automatic_relist":false,
   "date_created":"2016-01-18T18:01:14.574Z",
   "last_updated":"2016-01-18T18:01:14.574Z"
}



Awesome! You have just listed a product with custom variation. Go to the listing through the permalink to check how your product with design variation is shown in our Marketplace.

How to update custom variations

You have already learned to publish with custom variations and, most probably, you will need to update them when updating prices, adding variations or modifying the values of some published attribute.
For example, let’s suppose you listed.
To perform changes on a product with variations or a particular variation, you will have to get the variation_id by looking the product variations up as follows:
Call:

curl -X GET https://api.mercadolibre.com/items/{Item_id}/variations

Example:

curl -X GET https://api.mercadolibre.com/items/MLA601053403/variations

Response:

{
    "id": 10541993184,
    "attribute_combinations": [
      {
        "id": null,
        "name": "Diseño",
        "value_id": null,
        "value_name": "Bulldog"
      }
    ],
    "price": 1000,
    "available_quantity": 3,
    "sold_quantity": 0,
    "picture_ids": [
      "21150-MLA20204290696_112014"
    ],
    "seller_custom_field": null
  },
  {
    "id": 10541993186,
    "attribute_combinations": [
      {
        "id": null,
        "name": "Diseño",
        "value_id": null,
        "value_name": "Búho"
      }
    ],
    "price": 1000,
    "available_quantity": 3,
    "sold_quantity": 0,
    "picture_ids": [
      "21124-MLA20204291671_112014"
    ],
    "seller_custom_field": null
  }



Once you have the Ids for each variation, you can look up for each of them by adding the variaton_id at the end of the GET.
Call:

curl -X GET https://api.mercadolibre.com/items/{Item_id}/variations/{Variation_id}

Example:

curl -X GET https://api.mercadolibre.com/items/MLA601053403/variations/10541993184

Response:

{
  "id": 10541993184,
  "attribute_combinations": [
    {
      "id": null,
      "name": "Diseño",
      "value_id": null,
      "value_name": "Bulldog"
    }
  ],
  "price": 1000,
  "available_quantity": 3,
  "sold_quantity": 0,
  "picture_ids": [
    "21150-MLA20204290696_112014"
  ],
  "seller_custom_field": null,
  "attributes": [
  ]
}



Different types of changes can be performed on a listing with variations. The following guideline shows how to work in each particular case.
If you need to add an image to an existing variation, the image URL will have to be added to the product general pictures array and to the variation’s, as well. Also, since the update will be performed on the items resource, it is necessary to add the Ids for each existing variation on the Json, otherwise, the API will interpret you do not want to keep them on the product listing.
Example:

curl -XPUT -H "Content-type: application/json" -d '{
  "pictures":[  
    { "id":"21124-MLA20204291671_112014" },
    { "id":"21150-MLA20204290696_112014" },
    { "source": "http://mla-s1-p.mlstatic.com/funda-marc-jacobs-3d-iphone-5-5s-5c-bulldog-cebra-buho-732301-MLA20299187840_052015-F.jpg" }
  ],
  "variations":[  
    { "id":10541993184},
    { "id":10541993186,
       "picture_ids":[  
          "21124-MLA20204291671_112014",
          "http://mla-s1-p.mlstatic.com/funda-marc-jacobs-3d-iphone-5-5s-5c-bulldog-cebra-buho-732301-MLA20299187840_052015-F.jpg"
       ]
    }
  ]
}' https://api.mercadolibre.com/items/MLA601053403?access_token=$ACCESS_TOKEN



If you do not want to keep the previous images, do not add them to the Json and they will be automatically detached.
Let’s say now it is available a new design for your product. You can add a new variation on the same listing.
Example:

curl -X POST -d '{
	"attribute_combinations": [{
		"name": "Diseño",
		"value_name": "Cebra"
	}],
	"price": 1000,
	"available_quantity": 3,
	"picture_ids": ["209411-MLA20552996931_012016"]
}' https://api.mercadolibre.com/items/MLA601053403/variations?access_token=$ACCESS_TOKEN



OK. Now the listing has three design variations: Bulldog, Búho and Cebra.
If you want to modify a non-attibute type variation field, you will have to do something similar. In this case, you will have to replace the value of “seller_custom_field” field, which previously was set to null, with a String with the product SKU:
Example:

curl -X PUT -d '{"seller_custom_field": "123456789000"}' https://api.mercadolibre.com/items/MLA601053403/variations/10541993184?access_token=$ACCESS_TOKEN



If you need to change other listing aspects non-related to variations, follow the tutorials for Synchronizing listings.

Notes:

  • If you paid attention through this tutorial, you are now able to modify items with variations.
  • The item will always have a single price for all its variations.

Relisting custom variations

If your listing finished but you still have some variations in stock, you can relist them sending the variations you wish to keep, available quantity, and price of each of them.
Example:

curl -X POST -H "Content-Type: application/json" -d'{
    "listing_type_id": "bronze",
    "variations": [
        {
            "id": 10541993184,
            "price": 1000,
            "quantity": 2
        },
        {
            "id": 10541993186,
            "price": 1000,
            "quantity": 2
        },
                {
            "id": 10542199553,
            "price": 1000,
            "quantity": 1
        }
    ] }' https://api.mercadolibre.com/items/MLA601053403/relist?access_token=¢ACCESS_TOKEN

As you can see in the response, when a product is relisted, a new listing is generated so we will renew your variations “Item_id” and “Id”.

Deleting custom variations

Now that you know how get the Id of each variation, deleting one or more variations of an item will be a simple task.
Example:

curl -X DELETE 'https://api.mercadolibre.com/items/MLA601053403/variations/10542199553?access_token=$ACCESS_TOKEN'



Well done! You have already learned how to delete variations for an item.

Please rate this

Standard variations

A standard variation is a default attribute which is tied to a certain category.

Contents:



VipVariacionesEstandares

How to use standard variations?

Each category has default variations that can be combined between them. For example: size and color (for Fashion) or only voltage (for consumer electronics). Before listing an item with variations, make sure you checked which attributes are available for that category, and the allowed values for each of them.

How to list items with standard variations?

You must check the category_id of the chosen category you want to list in.
Call:

curl -X GET https://api.mercadolibre.com/categories/{Category_id}

Example:

https://api.mercadolibre.com/categories/MLA374515

Response:

{
  "id": "MLA374515",
  "name": "Polleras Largas",
  "picture": null,
  "permalink": null,
  "total_items_in_this_category": 296,
  "path_from_root": [
    {
      "id": "MLA1430",
      "name": "Ropa y Accesorios"
    },
    {
      "id": "MLA373771",
      "name": "Polleras"
    },
    {
      "id": "MLA7297",
      "name": "Mujer"
    },
    {
      "id": "MLA373876",
      "name": "Polleras Plisadas"
    },
    {
      "id": "MLA374515",
      "name": "Polleras Largas"
    }
  ],
  "children_categories": [
  ],
  "attribute_types": "variations",
  "settings": {
    "adult_content": false,
    "buying_allowed": true,
    "buying_modes": [
      "buy_it_now",
      "auction"
    ],
    "coverage_areas": "not_allowed",
    "currencies": [
      "ARS"
    ],
    "fragile": false,
    "immediate_payment": "optional",
    "item_conditions": [
      "not_specified",
      "used",
      "new"
    ],
    "items_reviews_allowed": false,
    "max_description_length": 50000,
    "max_pictures_per_item": 36,
    "max_sub_title_length": 70,
    "max_title_length": 60,
    "price": "required",
    "restrictions": [
    ],
    "rounded_address": false,
    "seller_contact": "not_allowed",
    "shipping_modes": [
      "not_specified",
      "custom",
      "me2",
      "me1"
    ],
    "shipping_options": [
      "carrier",
      "custom"
    ],
    "shipping_profile": "optional",
    "show_contact_information": false,
    "simple_shipping": "optional",
    "stock": "required",
    "tags": [
    ],
    "vip_subdomain": "articulo",
    "mirror_category": null,
    "listing_allowed": true,
    "maximum_price": null,
    "minimum_price": null
  },
  "meta_categ_id": 59801,
  "attributable": false
}



Category allows variations if the answer includes the field “attribute_types”: “variations”.
In order to know which attributes are available for the chosen category, please proceed as follows:
Call:

curl -X GET https://api.mercadolibre.com/categories/{Category_id}/attributes

Example:

https://api.mercadolibre.com/categories/MLA374515/attributes

Response:

[
  {
    "id": "GENDER",
    "name": "Género",
    "value_type": "list",
    "tags": {
      "fixed": true
    },
    "values": [
      {
        "id": "female",
        "name": "Mujer"
      }
    ],
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
  {
    "id": "Season",
    "name": "Season",
    "value_type": "list",
    "tags": {
      "fixed": true
    },
    "values": [
      {
        "id": "Season-All-Season",
        "name": "All-Season"
      }
    ],
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
  {
    "id": "93000",
    "name": "Talle",
    "type": "size",
    "value_type": "list",
    "tags": {
      "allow_variations": true,
      "required": true
    },
    "values": [
      {
        "id": "101993",
        "name": "XS"
      },
      {
        "id": "101994",
        "name": "S"
      },
      {
        "id": "101995",
        "name": "M"
      },
      {
        "id": "101996",
        "name": "L"
      },
      {
        "id": "101997",
        "name": "XL"
      },
      {
        "id": "101998",
        "name": "XXL"
      },
      {
        "id": "101999",
        "name": "XXXL"
      },
      {
        "id": "04ecc99",
        "name": "4XL"
      },
      {
        "id": "102000",
        "name": "U"
      },
      {
        "id": "102001",
        "name": "AM"
      }
    ],
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
  {
    "id": "83000",
    "name": "Color Primario",
    "type": "color",
    "value_type": "list",
    "tags": {
      "allow_variations": true,
      "required": true
    },
    "values": [
      {
        "id": "91993",
        "name": "Rojo",
        "metadata": {
          "rgb": "#FF0000"
        }
      },
      {
        "id": "91994",
        "name": "Rosa",
        "metadata": {
          "rgb": "#F4CCCC"
        }
      },
      {
        "id": "91995",
        "name": "Terracota",
        "metadata": {
          "rgb": "#E06666"
        }
      },
      {
        "id": "91996",
        "name": "Bordó",
        "metadata": {
          "rgb": "#990000"
        }
      },
      {
        "id": "91997",
        "name": "Naranja",
        "metadata": {
          "rgb": "#FF9900"
        }
      },
      {
        "id": "91998",
        "name": "Beige",
        "metadata": {
          "rgb": "#FCE5CD"
        }
      },
      {
        "id": "91999",
        "name": "Piel",
        "metadata": {
          "rgb": "#F6B26B"
        }
      },
      {
        "id": "92000",
        "name": "Marrón",
        "metadata": {
          "rgb": "#B45F06"
        }
      },
      {
        "id": "92001",
        "name": "Amarillo",
        "metadata": {
          "rgb": "#FFFF00"
        }
      },
      {
        "id": "92002",
        "name": "Crema",
        "metadata": {
          "rgb": "#FFF2CC"
        }
      },
      {
        "id": "92003",
        "name": "Ocre",
        "metadata": {
          "rgb": "#FFD966"
        }
      },
      {
        "id": "92004",
        "name": "Dorado",
        "metadata": {
          "rgb": "#BF9000"
        }
      },
      {
        "id": "92005",
        "name": "Verde",
        "metadata": {
          "rgb": "#0C9800"
        }
      },
      {
        "id": "92006",
        "name": "Verde claro",
        "metadata": {
          "rgb": "#D9EAD3"
        }
      },
      {
        "id": "92007",
        "name": "Esmeralda",
        "metadata": {
          "rgb": "#93C47D"
        }
      },
      {
        "id": "92008",
        "name": "Verde oscuro",
        "metadata": {
          "rgb": "#38761D"
        }
      },
      {
        "id": "92009",
        "name": "Agua",
        "metadata": {
          "rgb": "#83DDFF"
        }
      },
      {
        "id": "92010",
        "name": "Azul cielo",
        "metadata": {
          "rgb": "#D0E0E3"
        }
      },
      {
        "id": "92020",
        "name": "Azul marino",
        "metadata": {
          "rgb": "#76A5AF"
        }
      },
      {
        "id": "92012",
        "name": "Azul petróleo",
        "metadata": {
          "rgb": "#134F5C"
        }
      },
      {
        "id": "92013",
        "name": "Azul",
        "metadata": {
          "rgb": "#1717FF"
        }
      },
      {
        "id": "92014",
        "name": "Celeste",
        "metadata": {
          "rgb": "#CFE2F3"
        }
      },
      {
        "id": "92015",
        "name": "Azul acero",
        "metadata": {
          "rgb": "#6FA8DC"
        }
      },
      {
        "id": "92016",
        "name": "Azul oscuro",
        "metadata": {
          "rgb": "#0B5394"
        }
      },
      {
        "id": "92017",
        "name": "Violeta oscuro",
        "metadata": {
          "rgb": "#7600FF"
        }
      },
      {
        "id": "92018",
        "name": "Lavanda",
        "metadata": {
          "rgb": "#D9D2E9"
        }
      },
      {
        "id": "92019",
        "name": "Lila",
        "metadata": {
          "rgb": "#8E7CC3"
        }
      },
      {
        "id": "92021",
        "name": "Fucsia",
        "metadata": {
          "rgb": "#E828FF"
        }
      },
      {
        "id": "92022",
        "name": "Salmón",
        "metadata": {
          "rgb": "#EAD1DC"
        }
      },
      {
        "id": "92023",
        "name": "Fucsia oscuro",
        "metadata": {
          "rgb": "#C27BA0"
        }
      },
      {
        "id": "92024",
        "name": "Púrpura",
        "metadata": {
          "rgb": "#741B47"
        }
      },
      {
        "id": "92025",
        "name": "Negro",
        "metadata": {
          "rgb": "#000000"
        }
      },
      {
        "id": "92026",
        "name": "Plateado",
        "metadata": {
          "rgb": "#CCCCCC"
        }
      },
      {
        "id": "92027",
        "name": "Gris",
        "metadata": {
          "rgb": "#666666"
        }
      },
      {
        "id": "92028",
        "name": "Blanco",
        "metadata": {
          "rgb": "#FFFFFF"
        }
      }
    ],
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
  {
    "id": "73001",
    "name": "Color Secundario",
    "type": "color",
    "value_type": "list",
    "tags": {
      "allow_variations": true
    },
    "values": [
      {
        "id": "82026",
        "name": "Rojo",
        "metadata": {
          "rgb": "#FF0000"
        }
      },
      {
        "id": "82027",
        "name": "Rosa",
        "metadata": {
          "rgb": "#F4CCCC"
        }
      },
      {
        "id": "82028",
        "name": "Terracota",
        "metadata": {
          "rgb": "#E06666"
        }
      },
      {
        "id": "82029",
        "name": "Bordó",
        "metadata": {
          "rgb": "#990000"
        }
      },
      {
        "id": "82030",
        "name": "Naranja",
        "metadata": {
          "rgb": "#FF9900"
        }
      },
      {
        "id": "82031",
        "name": "Beige",
        "metadata": {
          "rgb": "#FCE5CD"
        }
      },
      {
        "id": "82032",
        "name": "Piel",
        "metadata": {
          "rgb": "#F6B26B"
        }
      },
      {
        "id": "82033",
        "name": "Marrón",
        "metadata": {
          "rgb": "#B45F06"
        }
      },
      {
        "id": "82034",
        "name": "Amarillo",
        "metadata": {
          "rgb": "#FFFF00"
        }
      },
      {
        "id": "82035",
        "name": "Crema",
        "metadata": {
          "rgb": "#FFF2CC"
        }
      },
      {
        "id": "82036",
        "name": "Ocre",
        "metadata": {
          "rgb": "#FFD966"
        }
      },
      {
        "id": "82037",
        "name": "Dorado",
        "metadata": {
          "rgb": "#BF9000"
        }
      },
      {
        "id": "82038",
        "name": "Verde",
        "metadata": {
          "rgb": "#0C9800"
        }
      },
      {
        "id": "82039",
        "name": "Verde claro",
        "metadata": {
          "rgb": "#D9EAD3"
        }
      },
      {
        "id": "82040",
        "name": "Esmeralda",
        "metadata": {
          "rgb": "#93C47D"
        }
      },
      {
        "id": "82041",
        "name": "Verde oscuro",
        "metadata": {
          "rgb": "#38761D"
        }
      },
      {
        "id": "82042",
        "name": "Agua",
        "metadata": {
          "rgb": "#83DDFF"
        }
      },
      {
        "id": "82043",
        "name": "Azul cielo",
        "metadata": {
          "rgb": "#D0E0E3"
        }
      },
      {
        "id": "82044",
        "name": "Azul marino",
        "metadata": {
          "rgb": "#76A5AF"
        }
      },
      {
        "id": "82045",
        "name": "Azul petróleo",
        "metadata": {
          "rgb": "#134F5C"
        }
      },
      {
        "id": "82046",
        "name": "Azul",
        "metadata": {
          "rgb": "#1717FF"
        }
      },
      {
        "id": "82047",
        "name": "Celeste",
        "metadata": {
          "rgb": "#CFE2F3"
        }
      },
      {
        "id": "82048",
        "name": "Azul acero",
        "metadata": {
          "rgb": "#6FA8DC"
        }
      },
      {
        "id": "82049",
        "name": "Azul oscuro",
        "metadata": {
          "rgb": "#0B5394"
        }
      },
      {
        "id": "82050",
        "name": "Violeta oscuro",
        "metadata": {
          "rgb": "#7600FF"
        }
      },
      {
        "id": "82051",
        "name": "Lavanda",
        "metadata": {
          "rgb": "#D9D2E9"
        }
      },
      {
        "id": "82052",
        "name": "Lila",
        "metadata": {
          "rgb": "#8E7CC3"
        }
      },
      {
        "id": "82054",
        "name": "Fucsia",
        "metadata": {
          "rgb": "#E828FF"
        }
      },
      {
        "id": "82055",
        "name": "Salmón",
        "metadata": {
          "rgb": "#EAD1DC"
        }
      },
      {
        "id": "82056",
        "name": "Fucsia oscuro",
        "metadata": {
          "rgb": "#C27BA0"
        }
      },
      {
        "id": "82057",
        "name": "Púrpura",
        "metadata": {
          "rgb": "#741B47"
        }
      },
      {
        "id": "82058",
        "name": "Negro",
        "metadata": {
          "rgb": "#000000"
        }
      },
      {
        "id": "82059",
        "name": "Plateado",
        "metadata": {
          "rgb": "#CCCCCC"
        }
      },
      {
        "id": "82060",
        "name": "Gris",
        "metadata": {
          "rgb": "#666666"
        }
      },
      {
        "id": "82061",
        "name": "Blanco",
        "metadata": {
          "rgb": "#FFFFFF"
        }
      }
    ],
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  }
]



You now know which attributes and values are available for your listing’s variation. Please note and remember that it is required to send those attributes that include the tag “required”:true. In addition, you can only use in your attributes combination (variation) those attributes including the tag “allow_variations”:true.
For example, you may use size and color. But you cannot use “gender” or “season” since they are tagged as “fixed:true”. This means that the item will inherit those values automatically. There is no need to send them in your post.
Check the next example to see how to list a Fashion item with size and color variations:
Example:

curl -X POST -H "Content-Type: application/json" -d '{
   "title":"Test Item - No ofertar",
   "category_id":"MLA374515",
   "price":200,
   "currency_id":"ARS",
   "buying_mode":"buy_it_now",
   "listing_type_id":"bronze",
   "condition":"new",
   "description": "Item de Test - No ofertar",
   "variations":[
    {
      "attribute_combinations":[
          {
            "id":"83000",
            "value_id":"92028"
          },
          {
            "id":"93000",
            "value_id":"101994"
          }
      ],
      "available_quantity":1,
      "price":200,
      "picture_ids":[
          "http://picture-cdn.wheretoget.it/lc6kzg-i.jpg"
      ]
    },
    {
      "attribute_combinations":[
          {
            "id":"83000",
            "value_id":"91994"
          },
          {
            "id":"93000",
            "value_id":"101995"
          }
      ],
      "available_quantity":1,
      "price":200,
      "picture_ids":[
          "https://s-media-cache-ak0.pinimg.com/736x/63/9c/a0/639ca03b5ca79e73002b4f2d4776d03b.jpg"
      ]
    }
   ]
}' 'https://api.mercadolibre.com/items?access_token=¢ACCESS_TOKEN

Response:

{  
   "id":"MLA599074368",
   "site_id":"MLA",
   "title":"Test Item - No Ofertar",
   "subtitle":null,
   "seller_id":202593498,
   "category_id":"MLA374515",
   "official_store_id":null,
   "price":200,
   "base_price":200,
   "original_price":null,
   "currency_id":"ARS",
   "initial_quantity":2,
   "available_quantity":2,
   "sold_quantity":0,
   "buying_mode":"buy_it_now",
   "listing_type_id":"bronze",
   "start_time":"2016-01-07T15:49:51.419Z",
   "stop_time":"2016-03-07T15:49:51.419Z",
   "end_time":"2016-03-07T15:49:51.419Z",
   "condition":"new",
   "permalink":"http://articulo.mercadolibre.com.ar/MLA-599074368-test-item-no-ofertar-_JM",
   "thumbnail":"http://www.mercadolibre.com/jm/img?s=STC&v=I&f=proccesing_image_es.jpg",
   "secure_thumbnail":"https://www.mercadolibre.com/jm/img?s=STC&v=I&f=proccesing_image_es.jpg",
   "pictures":[  
      {  
         "id":"749311-MLA20539854842_012016",
         "url":"http://www.mercadolibre.com/jm/img?s=STC&v=O&f=proccesing_image_es.jpg",
         "secure_url":"https://www.mercadolibre.com/jm/img?s=STC&v=O&f=proccesing_image_es.jpg",
         "size":"500x500",
         "max_size":"500x500",
         "quality":""
      },
      {  
         "id":"710411-MLA20539854841_012016",
         "url":"http://www.mercadolibre.com/jm/img?s=STC&v=O&f=proccesing_image_es.jpg",
         "secure_url":"https://www.mercadolibre.com/jm/img?s=STC&v=O&f=proccesing_image_es.jpg",
         "size":"500x500",
         "max_size":"500x500",
         "quality":""
      }
   ],
   "video_id":null,
   "descriptions":[  
      {  
         "id":"MLA599074368-1003328092"
      }
   ],
   "accepts_mercadopago":true,
   "non_mercado_pago_payment_methods":[  

   ],
   "shipping":{  
      "mode":"not_specified",
      "local_pick_up":false,
      "free_shipping":false,
      "methods":[  

      ],
      "dimensions":null,
      "tags":[  

      ]
   },
   "international_delivery_mode":"none",
   "seller_address":{  
      "id":175597910,
      "comment":"",
      "address_line":"Test Address 123",
      "zip_code":"1414",
      "city":{  
         "id":"",
         "name":"Palermo"
      },
      "state":{  
         "id":"AR-C",
         "name":"Capital Federal"
      },
      "country":{  
         "id":"AR",
         "name":"Argentina"
      },
      "latitude":-34.5711496,
      "longitude":-58.4232966,
      "search_location":{  
         "neighborhood":{  
            "id":"",
            "name":""
         },
         "city":{  
            "id":"TUxBQ0NBUGZlZG1sYQ",
            "name":"Capital Federal"
         },
         "state":{  
            "id":"TUxBUENBUGw3M2E1",
            "name":"Capital Federal"
         }
      }
   },
   "seller_contact":null,
   "location":{  

   },
   "geolocation":{  
      "latitude":-34.5711496,
      "longitude":-58.4232966
   },
   "coverage_areas":[  

   ],
   "attributes":[  
      {  
         "id":"GENDER",
         "name":"Género",
         "value_id":"female",
         "value_name":"Mujer",
         "attribute_group_id":"DFLT",
         "attribute_group_name":"Otros"
      },
      {  
         "id":"Season",
         "name":"Season",
         "value_id":"Season-All-Season",
         "value_name":"All-Season",
         "attribute_group_id":"DFLT",
         "attribute_group_name":"Otros"
      }
   ],
   "listing_source":"",
   "variations":[  
      {  
         "id":10448277573,
         "attribute_combinations":[  
            {  
               "id":"83000",
               "name":"Color Primario",
               "value_id":"92028",
               "value_name":"Blanco"
            },
            {  
               "id":"93000",
               "name":"Talle",
               "value_id":"101994",
               "value_name":"S"
            }
         ],
         "price":200,
         "available_quantity":1,
         "sold_quantity":0,
         "picture_ids":[  
            "749311-MLA20539854842_012016"
         ],
         "seller_custom_field":null,
         "attributes":[  

         ]
      },
      {  
         "id":10448277576,
         "attribute_combinations":[  
            {  
               "id":"83000",
               "name":"Color Primario",
               "value_id":"91994",
               "value_name":"Rosa"
            },
            {  
               "id":"93000",
               "name":"Talle",
               "value_id":"101995",
               "value_name":"M"
            }
         ],
         "price":200,
         "available_quantity":1,
         "sold_quantity":0,
         "picture_ids":[  
            "710411-MLA20539854841_012016"
         ],
         "seller_custom_field":null,
         "attributes":[  

         ]
      }
   ],
   "status":"not_yet_active",
   "sub_status":[  

   ],
   "tags":[  

   ],
   "warranty":null,
   "catalog_product_id":null,
   "seller_custom_field":null,
   "parent_item_id":null,
   "differential_pricing":null,
   "deal_ids":[  

   ],
   "automatic_relist":false,
   "date_created":"2016-01-07T15:49:51.753Z",
   "last_updated":"2016-01-07T15:49:51.753Z"
}



Notes:

  • Price should be the same for all variations and items.
  • The url of the image should be the same for all color’s variations.

Possible errors

Our API automatically does certain validations on the JSON you send. If you don’t include any required attribute, that post will be rejected and you will get a validation error message.
For example, if you forget including the Primary Color (which is a required attribute according to category MLA374515) in a Fashion listing, you will get the following answer:

{  
   "message":"Validation error",
   "error":"validation_error",
   "status":400,
   "cause":[  
      {  
         "code":"item.attributes.missing_required",
         "message":"The attributes [83000] are required for category MLA374515. Check the attribute is present in the attributes list or in all variation attributes combination."
      }
   ]
}



Another frequent error consists in sending an attribute with a not-accepted value according to the allowed values for that category. Check frequent errors and their meaning.
To avoid making these kind of mistakes when listing, we suggest validating your JSON before posting it, in our item validator. Learn how to validate an item before posting it.

Modify standard variations

You already know how to list products with variations. You then might need to do some changes on these items, or on some particular variations like update stock, pictures, add some new variation or modify existing ones.
In order to modify items with variations, or a particular variation, you will need to know the variation_id, and get the item variations doing as follows:
Call:

curl -X GET https://api.mercadolibre.com/items/{Item_id}/variations

Example:

curl -X GET https://api.mercadolibre.com/items/MLA599074368/variations

Response:

{
    "id": 10448277573,
    "attribute_combinations": [
      {
        "id": "83000",
        "name": "Color Primario",
        "value_id": "92028",
        "value_name": "Blanco"
      },
      {
        "id": "93000",
        "name": "Talle",
        "value_id": "101994",
        "value_name": "S"
      }
    ],
    "price": 200,
    "available_quantity": 1,
    "sold_quantity": 0,
    "picture_ids": [
      "749311-MLA20539854842_012016"
    ],
    "seller_custom_field": null
  },
  {
    "id": 10448277576,
    "attribute_combinations": [
      {
        "id": "83000",
        "name": "Color Primario",
        "value_id": "91994",
        "value_name": "Rosa"
      },
      {
        "id": "93000",
        "name": "Talle",
        "value_id": "101995",
        "value_name": "M"
      }
    ],
    "price": 200,
    "available_quantity": 1,
    "sold_quantity": 0,
    "picture_ids": [
      "710411-MLA20539854841_012016"
    ],
    "seller_custom_field": null
  }



Once you each variations_id, you can check one particular variation adding the variation_id at the end of the apicall:
Call:

curl -X GET https://api.mercadolibre.com/items/{Item_id}/variations/{Variation_id}

Example:

curl -X GET https://api.mercadolibre.com/items/MLA599074368/variations/10448277573

Response:

{
  "id": 10448277573,
  "attribute_combinations": [
    {
      "id": "83000",
      "name": "Color Primario",
      "value_id": "92028",
      "value_name": "Blanco"
    },
    {
      "id": "93000",
      "name": "Talle",
      "value_id": "101994",
      "value_name": "S"
    }
  ],
  "price": 200,
  "available_quantity": 1,
  "sold_quantity": 0,
  "picture_ids": [
    "749311-MLA20539854842_012016"
  ],
  "seller_custom_field": null,
  "attributes": [
  ]
}



There are several kinds of modifications you may need on an item with variations. Next, you will find an explanation for each of them.

Add new variation

If you have new sizes in stock for a certain item, you will be able to add a new variation:
Example:

curl -X POST -d '{"attribute_combinations":[{"id":"83000","value_id":"91994"},{"id":"93000","value_id":"101996"}],"price":200,"available_quantity":3,"picture_ids":["710411-MLA20539854841_012016"]}' https://api.mercadolibre.com/items/MLA599074368/variations?access_token=¢ACCESS_TOKEN

Response:

[  
   {  
      "id":10448277573,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"92028",
            "value_name":"Blanco"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101994",
            "value_name":"S"
         }
      ],
      "price":200,
      "available_quantity":1,
      "sold_quantity":0,
      "picture_ids":[  
         "749311-MLA20539854842_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   },
   {  
      "id":10448277576,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101995",
            "value_name":"M"
         }
      ],
      "price":200,
      "available_quantity":1,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   },
   {  
      "id":10448293016,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101996",
            "value_name":"L"
         }
      ],
      "price":200,
      "available_quantity":3,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   }
]



Well done! if you check the item you will find a new size for one of the colors of your product.

Add news attributes

It is possible that in some case you need to add a new attribute to an existing variation. Please follow the instructions below to know how to add a secondary color to one of our variations.
Example:

curl -X PUT -d '{ "attribute_combinations":[  {  "id":"83000","value_id":"91994"},{ "id":"93000","value_id":"101995"},{  "id":"73001","value_id":"82035"}]}' https://api.mercadolibre.com/items/MLA599074368/variations/10448277576?access_token=$ACCESS_TOKEN

Response:

[  
   {  
      "id":10448277573,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"92028",
            "value_name":"Blanco"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101994",
            "value_name":"S"
         }
      ],
      "price":200,
      "available_quantity":1,
      "sold_quantity":0,
      "picture_ids":[  
         "749311-MLA20539854842_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   },
   {  
      "id":10448277576,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"73001",
            "name":"Color Secundario",
            "value_id":"82035",
            "value_name":"Crema"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101995",
            "value_name":"M"
         }
      ],
      "price":200,
      "available_quantity":1,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   },
   {  
      "id":10448293016,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101996",
            "value_name":"L"
         }
      ],
      "price":200,
      "available_quantity":3,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   }
]



If you need to modify the other fields within the variation, which are not attributes, you must proceed similar. In the following example, the field “seller_custom_field” will be updated:
Example:

curl -X PUT -d '{"seller_custom_field": "21000093"}' https://api.mercadolibre.com/items/MLA599074368/variations/10448277576?access_token=¢ACCESS_TOKEN

Response:

[  
   {  
      "id":10448277573,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"92028",
            "value_name":"Blanco"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101994",
            "value_name":"S"
         }
      ],
      "price":200,
      "available_quantity":1,
      "sold_quantity":0,
      "picture_ids":[  
         "749311-MLA20539854842_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   },
   {  
      "id":10448277576,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"73001",
            "name":"Color Secundario",
            "value_id":"82035",
            "value_name":"Crema"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101995",
            "value_name":"M"
         }
      ],
      "price":200,
      "available_quantity":1,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016"
      ],
      "seller_custom_field":"21000093",
      "attributes":[  

      ]
   },
   {  
      "id":10448293016,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101996",
            "value_name":"L"
         }
      ],
      "price":200,
      "available_quantity":3,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   }
]


Add images

If you need to add an image to an existing variation, you must send the image URL in both: in the item images array, and in the variation images array. In addition, since update will be done on items resource, it is important to also send each existing variation ID in the JSON. If you don’t, the API will consider you are willing to delete those variations.
Example:

curl -XPUT -H "Content-type: application/json" -d '{
  "pictures":[  
    { "id":"749311-MLA20539854842_012016" },
    { "id":"710411-MLA20539854841_012016" },
    { "source": "https://s-media-cache-ak0.pinimg.com/236x/16/d0/29/16d0294482674bb2ddefd06f49896ef1.jpg" }
  ],
  "variations":[  
    { "id":10448277573 },
    { "id":10448277576,
       "picture_ids":[  
          "710411-MLA20539854841_012016",
          "https://s-media-cache-ak0.pinimg.com/236x/16/d0/29/16d0294482674bb2ddefd06f49896ef1.jpg"
       ]
    },
    { "id":10448293016 }
  ]
}' https://api.mercadolibre.com/items/MLA599074368?access_token=$ACCESS_TOKEN

Response:

{
    "accepts_mercadopago": true,
    "attributes": [
        {
            "attribute_group_id": "DFLT",
            "attribute_group_name": "Otros",
            "id": "GENDER",
            "name": "Género",
            "value_id": "female",
            "value_name": "Mujer"
        },
        {
            "attribute_group_id": "DFLT",
            "attribute_group_name": "Otros",
            "id": "Season",
            "name": "Season",
            "value_id": "Season-All-Season",
            "value_name": "All-Season"
        }
    ],
    "automatic_relist": false,
    "available_quantity": 5,
    "base_price": 200,
    "buying_mode": "buy_it_now",
    "catalog_product_id": null,
    "category_id": "MLA374515",
    "condition": "new",
    "coverage_areas": [],
    "currency_id": "ARS",
    "date_created": "2016-01-07T15:49:51.000Z",
    "deal_ids": [],
    "descriptions": [
        {
            "id": "MLA599074368-1003328092"
        }
    ],
    "differential_pricing": null,
    "end_time": "2016-03-07T15:49:51.000Z",
    "geolocation": {
        "latitude": -34.571149599999998,
        "longitude": -58.4232966
    },
    "id": "MLA599074368",
    "initial_quantity": 5,
    "international_delivery_mode": "none",
    "last_updated": "2016-01-07T17:37:08.164Z",
    "listing_source": "",
    "listing_type_id": "bronze",
    "location": {},
    "non_mercado_pago_payment_methods": [],
    "official_store_id": null,
    "original_price": null,
    "parent_item_id": null,
    "permalink": "http://articulo.mercadolibre.com.ar/MLA-599074368-test-item-no-ofertar-_JM",
    "pictures": [
        {
            "id": "749311-MLA20539854842_012016",
            "max_size": "300x300",
            "quality": "",
            "secure_url": "https://a248.e.akamai.net/mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-O.jpg",
            "size": "300x300",
            "url": "http://mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-O.jpg"
        },
        {
            "id": "710411-MLA20539854841_012016",
            "max_size": "500x622",
            "quality": "",
            "secure_url": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/710411-MLA20539854841_012016-O.jpg",
            "size": "401x500",
            "url": "http://mla-s1-p.mlstatic.com/710411-MLA20539854841_012016-O.jpg"
        },
        {
            "id": "230411-MLA20540036877_012016",
            "max_size": "236x455",
            "quality": "",
            "secure_url": "https://a248.e.akamai.net/mla-s2-p.mlstatic.com/230411-MLA20540036877_012016-O.jpg",
            "size": "236x455",
            "url": "http://mla-s2-p.mlstatic.com/230411-MLA20540036877_012016-O.jpg"
        }
    ],
    "price": 200,
    "secure_thumbnail": "https://a248.e.akamai.net/mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-I.jpg",
    "seller_address": {
        "address_line": "Test Address 123",
        "city": {
            "id": "",
            "name": "Palermo"
        },
        "comment": "",
        "country": {
            "id": "AR",
            "name": "Argentina"
        },
        "id": 175597910,
        "latitude": -34.571149599999998,
        "longitude": -58.4232966,
        "search_location": {
            "city": {
                "id": "TUxBQ0NBUGZlZG1sYQ",
                "name": "Capital Federal"
            },
            "neighborhood": {
                "id": "",
                "name": ""
            },
            "state": {
                "id": "TUxBUENBUGw3M2E1",
                "name": "Capital Federal"
            }
        },
        "state": {
            "id": "AR-C",
            "name": "Capital Federal"
        },
        "zip_code": "1414"
    },
    "seller_contact": null,
    "seller_custom_field": null,
    "seller_id": 202593498,
    "shipping": {
        "dimensions": null,
        "free_shipping": false,
        "local_pick_up": false,
        "methods": [],
        "mode": "not_specified",
        "tags": []
    },
    "site_id": "MLA",
    "sold_quantity": 0,
    "start_time": "2016-01-07T15:49:51.000Z",
    "status": "active",
    "stop_time": "2016-03-07T15:49:51.000Z",
    "sub_status": [],
    "subtitle": null,
    "tags": [],
    "thumbnail": "http://mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-I.jpg",
    "title": "Test Item - No Ofertar",
    "variations": [
        {
            "attribute_combinations": [
                {
                    "id": "83000",
                    "name": "Color Primario",
                    "value_id": "92028",
                    "value_name": "Blanco"
                },
                {
                    "id": "93000",
                    "name": "Talle",
                    "value_id": "101994",
                    "value_name": "S"
                }
            ],
            "attributes": [],
            "available_quantity": 1,
            "id": 10448277573,
            "picture_ids": [
                "749311-MLA20539854842_012016"
            ],
            "price": 200,
            "seller_custom_field": null,
            "sold_quantity": 0
        },
        {
            "attribute_combinations": [
                {
                    "id": "83000",
                    "name": "Color Primario",
                    "value_id": "91994",
                    "value_name": "Rosa"
                },
                {
                    "id": "73001",
                    "name": "Color Secundario",
                    "value_id": "82035",
                    "value_name": "Crema"
                },
                {
                    "id": "93000",
                    "name": "Talle",
                    "value_id": "101995",
                    "value_name": "M"
                }
            ],
            "attributes": [],
            "available_quantity": 1,
            "id": 10448277576,
            "picture_ids": [
                "710411-MLA20539854841_012016",
                "230411-MLA20540036877_012016"
            ],
            "price": 200,
            "seller_custom_field": "21000093",
            "sold_quantity": 0
        },
        {
            "attribute_combinations": [
                {
                    "id": "83000",
                    "name": "Color Primario",
                    "value_id": "91994",
                    "value_name": "Rosa"
                },
                {
                    "id": "93000",
                    "name": "Talle",
                    "value_id": "101996",
                    "value_name": "L"
                }
            ],
            "attributes": [],
            "available_quantity": 3,
            "id": 10448293016,
            "picture_ids": [
                "710411-MLA20539854841_012016"
            ],
            "price": 200,
            "seller_custom_field": null,
            "sold_quantity": 0
        }
    ],
    "video_id": null,
    "warranty": null
}



In case you do not need to keep previous images, just avoid sending them in the JSON and they will be deleted automatically.

Modify price

If you paid attention through this tutorial, you are now able to modify items with variations.
Note: The item will always have a single price for all its variations.

Example:

curl -XPUT -H "Content-type: application/json" -d '{
"variations": [{
"id": 12532469522,
"attribute_combinations": [{
"id": "83000",
"name": "Color Primario",
"value_id": "92028",
"value_name": "Blanco"
}, {
"id": "93000",
"name": "Talle",
"value_id": "101994",
"value_name": "S"
}],
"price": 205,
"available_quantity": 1,
"sold_quantity": 0,
"picture_ids": [
"565505-MLA25031883106_092016"
],
"seller_custom_field": null,
"attributes": []
}, {
"id": 12532469525,
"attribute_combinations": [{
"id": "83000",
"name": "Color Primario",
"value_id": "91994",
"value_name": "Rosa"
}, {
"id": "93000",
"name": "Talle",
"value_id": "101995",
"value_name": "M"
}],
"price": 205,
"available_quantity": 1,
"sold_quantity": 0,
"picture_ids": [
"643505-MLA25031883107_092016"
],
"seller_custom_field": null,
"attributes": []
}, {
"id": 12532516877,
"attribute_combinations": [{
"id": "83000",
"name": "Color Primario",
"value_id": "91994",
"value_name": "Rosa"
}, {
"id": "93000",
"name": "Talle",
"value_id": "101996",
"value_name": "L"
}],
"price": 205,
"available_quantity": 3,
"sold_quantity": 0,
"picture_ids": [
"643505-MLA25031883107_092016"
],
"seller_custom_field": null,
"attributes": []
}]

}' https://api.mercadolibre.com/items/MLA633592671?access_token=$ACCESS_TOKEN

Response:/span>

{
"id": "MLA633592671",
"site_id": "MLA",
"title": "Your New Title",
"subtitle": null,
"seller_id": 207035636,
"category_id": "MLA374515",
"official_store_id": null,
"price": 205,
"base_price": 205,
"original_price": null,
"currency_id": "ARS",
"initial_quantity": 5,
"available_quantity": 5,
"sold_quantity": 0,
"buying_mode": "buy_it_now",
"listing_type_id": "gold_special",
"start_time": "2016-09-02T19:26:48.000Z",
"stop_time": "2036-08-28T19:26:48.000Z",
"end_time": "2036-08-28T19:26:48.000Z",
"expiration_time": "2016-11-21T20:12:07.644Z",
"condition": "new",
"permalink": "http://articulo.mercadolibre.com.ar/MLA-633592671-your-new-title-_JM",
"thumbnail": "http://www.mercadolibre.com/jm/img?s=STC&v=I&f=proccesing_image_es.jpg",
"secure_thumbnail": "https://www.mercadolibre.com/jm/img?s=STC&v=I&f=proccesing_image_es.jpg",
"pictures": [
{
"id": "565505-MLA25031883106_092016",
"url": "http://www.mercadolibre.com/jm/img?s=STC&v=O&f=proccesing_image_es.jpg",
"secure_url": "https://www.mercadolibre.com/jm/img?s=STC&v=O&f=proccesing_image_es.jpg",
"size": "500x500",
"max_size": "500x500",
"quality": ""
},
{
"id": "643505-MLA25031883107_092016",
"url": "http://www.mercadolibre.com/jm/img?s=STC&v=O&f=proccesing_image_es.jpg",
"secure_url": "https://www.mercadolibre.com/jm/img?s=STC&v=O&f=proccesing_image_es.jpg",
"size": "500x500",
"max_size": "500x500",
"quality": ""
}
],
"video_id": null,
"descriptions": [
{
"id": "MLA633592671-1168547708"
}
],
"accepts_mercadopago": true,
"non_mercado_pago_payment_methods": [],
"shipping": {
"mode": "me2",
"local_pick_up": false,
"free_shipping": false,
"methods": [],
"dimensions": null,
"tags": []
},
"international_delivery_mode": "none",
"seller_address": {
"id": 179130864,
"comment": "",
"address_line": "Av La Voz Del Interior 123",
"zip_code": "5008",
"city": {
"id": "",
"name": "Capital"
},
"state": {
"id": "AR-X",
"name": "Córdoba"
},
"country": {
"id": "AR",
"name": "Argentina"
},
"latitude": -31.4200833,
"longitude": -64.1887761,
"search_location": {
"neighborhood": {
"id": "",
"name": ""
},
"city": {
"id": "",
"name": ""
},
"state": {
"id": "TUxBUENPUmFkZGIw",
"name": "Córdoba"
}
}
},
"seller_contact": null,
"location": {},
"geolocation": {
"latitude": -31.4200833,
"longitude": -64.1887761
},
"coverage_areas": [],
"attributes": [
{
"id": "GENDER",
"name": "Género",
"value_id": "female",
"value_name": "Mujer",
"attribute_group_id": "DFLT",
"attribute_group_name": "Otros"
},
{
"id": "Season",
"name": "Season",
"value_id": "Season-All-Season",
"value_name": "All-Season",
"attribute_group_id": "DFLT",
"attribute_group_name": "Otros"
}
],
"warnings": [],
"listing_source": "",
"variations": [
{
"id": 12532469522,
"attribute_combinations": [
{
"id": "83000",
"name": "Color Primario",
"value_id": "92028",
"value_name": "Blanco"
},
{
"id": "93000",
"name": "Talle",
"value_id": "101994",
"value_name": "S"
}
],
"price": 205,
"available_quantity": 1,
"sold_quantity": 0,
"picture_ids": [
"565505-MLA25031883106_092016"
],
"seller_custom_field": null,
"catalog_product_id": null,
"attributes": []
},
{
"id": 12532469525,
"attribute_combinations": [
{
"id": "83000",
"name": "Color Primario",
"value_id": "91994",
"value_name": "Rosa"
},
{
"id": "93000",
"name": "Talle",
"value_id": "101995",
"value_name": "M"
}
],
"price": 205,
"available_quantity": 1,
"sold_quantity": 0,
"picture_ids": [
"643505-MLA25031883107_092016"
],
"seller_custom_field": null,
"catalog_product_id": null,
"attributes": []
},
{
"id": 12532516877,
"attribute_combinations": [
{
"id": "83000",
"name": "Color Primario",
"value_id": "91994",
"value_name": "Rosa"
},
{
"id": "93000",
"name": "Talle",
"value_id": "101996",
"value_name": "L"
}
],
"price": 205,
"available_quantity": 3,
"sold_quantity": 0,
"picture_ids": [
"643505-MLA25031883107_092016"
],
"seller_custom_field": null,
"catalog_product_id": null,
"attributes": []
}
],
"status": "active",
"sub_status": [],
"tags": [
"immediate_payment"
],
"warranty": null,
"catalog_product_id": null,
"domain_id": null,
"seller_custom_field": null,
"parent_item_id": null,
"differential_pricing": null,
"deal_ids": [],
"automatic_relist": false,
"date_created": "2016-09-02T19:26:48.000Z",
"last_updated": "2016-09-02T20:12:07.680Z"
}

How to relist standard variations

If your listing finished, but you still have stock available in some of the variations, you can relist sending only those variations with stock. Remember to indicate quantity and price in each of them.
Example:

curl -X POST -H "Content-Type: application/json" -d'{
    "listing_type_id": "bronze",
    "variations": [
        {
            "id": 10448277573,
            "price": 1,
            "quantity": 200
        },
        {
            "id": 10448277576,
            "price": 4,
            "quantity": 200
        },
        {
            "id": 10448293016,
            "price": 2,
            "quantity": 200
        }
    ] }' https://api.mercadolibre.com/items/MLA599074368/relist?access_token=$ACCESS_TOKEN

Response:

{  
   "id":"MLA599099879",
   "site_id":"MLA",
   "title":"Test Item - No Ofertar",
   "subtitle":null,
   "seller_id":202593498,
   "category_id":"MLA374515",
   "official_store_id":null,
   "price":4,
   "base_price":4,
   "original_price":null,
   "currency_id":"ARS",
   "initial_quantity":600,
   "available_quantity":600,
   "sold_quantity":0,
   "buying_mode":"buy_it_now",
   "listing_type_id":"bronze",
   "start_time":"2016-01-07T18:00:38.518Z",
   "stop_time":"2016-03-07T18:00:38.518Z",
   "end_time":"2016-03-07T18:00:38.518Z",
   "condition":"new",
   "permalink":"http://articulo.mercadolibre.com.ar/MLA-599099879-test-item-no-ofertar-_JM",
   "thumbnail":"http://mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-I.jpg",
   "secure_thumbnail":"https://a248.e.akamai.net/mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-I.jpg",
   "pictures":[  
      {  
         "id":"749311-MLA20539854842_012016",
         "url":"http://mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-O.jpg",
         "secure_url":"https://a248.e.akamai.net/mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-O.jpg",
         "size":"300x300",
         "max_size":"300x300",
         "quality":""
      },
      {  
         "id":"710411-MLA20539854841_012016",
         "url":"http://mla-s1-p.mlstatic.com/710411-MLA20539854841_012016-O.jpg",
         "secure_url":"https://a248.e.akamai.net/mla-s1-p.mlstatic.com/710411-MLA20539854841_012016-O.jpg",
         "size":"401x500",
         "max_size":"500x622",
         "quality":""
      },
      {  
         "id":"230411-MLA20540036877_012016",
         "url":"http://mla-s2-p.mlstatic.com/230411-MLA20540036877_012016-O.jpg",
         "secure_url":"https://a248.e.akamai.net/mla-s2-p.mlstatic.com/230411-MLA20540036877_012016-O.jpg",
         "size":"236x455",
         "max_size":"236x455",
         "quality":""
      }
   ],
   "video_id":null,
   "descriptions":[  
      {  
         "id":"MLA599099879-1003435516"
      }
   ],
   "accepts_mercadopago":true,
   "non_mercado_pago_payment_methods":[  

   ],
   "shipping":{  
      "mode":"not_specified",
      "local_pick_up":false,
      "free_shipping":false,
      "methods":[  

      ],
      "dimensions":null,
      "tags":[  

      ]
   },
   "international_delivery_mode":"none",
   "seller_address":{  
      "id":175597910,
      "comment":"",
      "address_line":"Test Address 123",
      "zip_code":"1414",
      "city":{  
         "id":"",
         "name":"Palermo"
      },
      "state":{  
         "id":"AR-C",
         "name":"Capital Federal"
      },
      "country":{  
         "id":"AR",
         "name":"Argentina"
      },
      "latitude":-34.5711496,
      "longitude":-58.4232966,
      "search_location":{  
         "neighborhood":{  
            "id":"",
            "name":""
         },
         "city":{  
            "id":"TUxBQ0NBUGZlZG1sYQ",
            "name":"Capital Federal"
         },
         "state":{  
            "id":"TUxBUENBUGw3M2E1",
            "name":"Capital Federal"
         }
      }
   },
   "seller_contact":null,
   "location":{  

   },
   "geolocation":{  
      "latitude":-34.5711496,
      "longitude":-58.4232966
   },
   "coverage_areas":[  

   ],
   "attributes":[  
      {  
         "id":"GENDER",
         "name":"Género",
         "value_id":"female",
         "value_name":"Mujer",
         "attribute_group_id":"DFLT",
         "attribute_group_name":"Otros"
      },
      {  
         "id":"Season",
         "name":"Season",
         "value_id":"Season-All-Season",
         "value_name":"All-Season",
         "attribute_group_id":"DFLT",
         "attribute_group_name":"Otros"
      }
   ],
   "listing_source":"",
   "variations":[  
      {  
         "id":10449631060,
         "attribute_combinations":[  
            {  
               "id":"83000",
               "name":"Color Primario",
               "value_id":"92028",
               "value_name":"Blanco"
            },
            {  
               "id":"93000",
               "name":"Talle",
               "value_id":"101994",
               "value_name":"S"
            }
         ],
         "price":1,
         "available_quantity":200,
         "sold_quantity":0,
         "picture_ids":[  
            "749311-MLA20539854842_012016"
         ],
         "seller_custom_field":null,
         "attributes":[  

         ]
      },
      {  
         "id":10449631063,
         "attribute_combinations":[  
            {  
               "id":"83000",
               "name":"Color Primario",
               "value_id":"91994",
               "value_name":"Rosa"
            },
            {  
               "id":"73001",
               "name":"Color Secundario",
               "value_id":"82035",
               "value_name":"Crema"
            },
            {  
               "id":"93000",
               "name":"Talle",
               "value_id":"101995",
               "value_name":"M"
            }
         ],
         "price":4,
         "available_quantity":200,
         "sold_quantity":0,
         "picture_ids":[  
            "710411-MLA20539854841_012016",
            "230411-MLA20540036877_012016"
         ],
         "seller_custom_field":"21000093",
         "attributes":[  

         ]
      },
      {  
         "id":10449631067,
         "attribute_combinations":[  
            {  
               "id":"83000",
               "name":"Color Primario",
               "value_id":"91994",
               "value_name":"Rosa"
            },
            {  
               "id":"93000",
               "name":"Talle",
               "value_id":"101996",
               "value_name":"L"
            }
         ],
         "price":2,
         "available_quantity":200,
         "sold_quantity":0,
         "picture_ids":[  
            "710411-MLA20539854841_012016"
         ],
         "seller_custom_field":null,
         "attributes":[  

         ]
      }
   ],
   "status":"not_yet_active",
   "sub_status":[  

   ],
   "tags":[  
      "dragged_bids_and_visits"
   ],
   "warranty":null,
   "catalog_product_id":null,
   "seller_custom_field":null,
   "parent_item_id":"MLA599074368",
   "differential_pricing":null,
   "deal_ids":[  

   ],
   "automatic_relist":false,
   "date_created":"2016-01-07T18:00:38.701Z",
   "last_updated":"2016-01-07T18:00:38.701Z"
}



As we can see in the answer, when you relist an item a new listing is generated. Therefore, item_id and variation_id’s must be renewed.

Delete standard variations

Now that you know each variation ID, deleting one or more variations will be an easy task.
Example:

curl -X DELETE 'https://api.mercadolibre.com/items/MLA599099879/variations/10449631060?access_token=¢ACCESS_TOKEN'

Response:

[  
   {  
      "id":10449631063,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"73001",
            "name":"Color Secundario",
            "value_id":"82035",
            "value_name":"Crema"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101995",
            "value_name":"M"
         }
      ],
      "price":4,
      "available_quantity":200,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016",
         "230411-MLA20540036877_012016"
      ],
      "seller_custom_field":"21000093",
      "attributes":[  

      ]
   },
   {  
      "id":10449631067,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101996",
            "value_name":"L"
         }
      ],
      "price":2,
      "available_quantity":200,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   }
]



As you can see, variation 10449631060 was deleted, and variations 10449631063 and 10449631067 were kept.

Next:
Custom Variations.

Please rate this

Listing prices calculator

The Listing Prices API is a read-only resource that offers many ways to know the fees of listing an item in MercadoLibre, so a seller can know exactly how much it’s going to cost to list under a certain listing_type for a given site, category, currency and quantity.

Contents:

Attribute description

AttributeDescription
listing_type_idListing type ID
listing_type_nameListing type name
listing_exposureListing exposure level
requires_pictureShows if the listing type requires at least one picture
currency_idCurrency id of the fees
listing_fee_amountListing fee amount
selling_fee_amountSelling fee amount

Filter by price

Retrieves different listing types and each associated fee in the local currency where the item price is 5000.

Example:

curl -X GET https://api.mercadolibre.com/sites/:site_id/listing_prices?price=5000

Response:

{
    "listing_type_id": "gold_pro",
    "listing_type_name": "Oro Premium Full",
    "listing_exposure": "highest",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 0,
    "sale_fee_amount": 1150,
    "free_relist": false,
    "stop_time": "2016-04-22T10:31:44.135-04:00"
},
{
    "listing_type_id": "gold_premium",
    "listing_type_name": "Oro Premium",
    "listing_exposure": "highest",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 250,
    "sale_fee_amount": 375,
    "free_relist": false,
    "stop_time": "2016-04-22T10:31:44.119-04:00"
},
{
    "listing_type_id": "gold_special",
    "listing_type_name": "Oro Profesional",
    "listing_exposure": "highest",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 0,
    "sale_fee_amount": 525,
    "free_relist": false,
    "stop_time": "2016-04-22T10:31:44.121-04:00"
},
{
    "listing_type_id": "gold",
    "listing_type_name": "Oro",
    "listing_exposure": "high",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 150,
    "sale_fee_amount": 375,
    "free_relist": false,
    "stop_time": "2016-04-22T10:31:44.133-04:00"
},
{
    "listing_type_id": "silver",
    "listing_type_name": "Plata",
    "listing_exposure": "mid",
    "requires_picture": false,
    "currency_id": "ARS",
    "listing_fee_amount": 50,
    "sale_fee_amount": 375,
    "free_relist": false,
    "stop_time": "2016-04-22T10:31:44.127-04:00"
},
{
    "listing_type_id": "bronze",
    "listing_type_name": "Bronce",
    "listing_exposure": "low",
    "requires_picture": false,
    "currency_id": "ARS",
    "listing_fee_amount": 0,
    "sale_fee_amount": 550,
    "free_relist": false,
    "stop_time": "2016-04-22T10:31:44.130-04:00"
},
{
    "listing_type_id": "free",
    "listing_type_name": "Gratuita",
    "listing_exposure": "lowest",
    "requires_picture": false,
    "currency_id": "ARS",
    "listing_fee_amount": 0,
    "sale_fee_amount": 0,
    "free_relist": false,
    "stop_time": "2016-04-22T10:31:44.116-04:00"
}


By price and listing_type

Retrieves listing fee associated to listing type Gold in the local currency where the item price is 5000.
Example:

curl -X GET https://api.mercadolibre.com/sites/:site_id/listing_prices?price=5000&listing_type_id=gold

Response:

{
    "listing_type_id": "gold",
    "listing_type_name": "Oro",
    "listing_exposure": "high",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 150,
    "sale_fee_amount": 375,
    "free_relist": false,
    "stop_time": "2016-04-22T10:32:39.264-04:00"
}


Filter by listing type and quantity

Retrieves different listing types and each associated fee in the local currency where the item price is 5000 and item quantity is 5.
Example:

curl -X GET https://api.mercadolibre.com/sites/:site_id/listing_prices?price=5000&quantity=5

Response:

{
    "listing_type_id": "gold_pro",
    "listing_type_name": "Oro Premium Full",
    "listing_exposure": "highest",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 0,
    "sale_fee_amount": 1150,
    "free_relist": false,
    "stop_time": "2016-04-22T10:33:22.631-04:00"
},
{
    "listing_type_id": "gold_premium",
    "listing_type_name": "Oro Premium",
    "listing_exposure": "highest",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 800,
    "sale_fee_amount": 375,
    "free_relist": false,
    "stop_time": "2016-04-22T10:33:22.614-04:00"
},
{
    "listing_type_id": "gold_special",
    "listing_type_name": "Oro Profesional",
    "listing_exposure": "highest",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 0,
    "sale_fee_amount": 525,
    "free_relist": false,
    "stop_time": "2016-04-22T10:33:22.617-04:00"
},
{
    "listing_type_id": "gold",
    "listing_type_name": "Oro",
    "listing_exposure": "high",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 480,
    "sale_fee_amount": 375,
    "free_relist": false,
    "stop_time": "2016-04-22T10:33:22.628-04:00"
},
{
    "listing_type_id": "silver",
    "listing_type_name": "Plata",
    "listing_exposure": "mid",
    "requires_picture": false,
    "currency_id": "ARS",
    "listing_fee_amount": 160,
    "sale_fee_amount": 375,
    "free_relist": false,
    "stop_time": "2016-04-22T10:33:22.622-04:00"
},
{
    "listing_type_id": "bronze",
    "listing_type_name": "Bronce",
    "listing_exposure": "low",
    "requires_picture": false,
    "currency_id": "ARS",
    "listing_fee_amount": 0,
    "sale_fee_amount": 550,
    "free_relist": false,
    "stop_time": "2016-04-22T10:33:22.624-04:00"
},
{
    "listing_type_id": "free",
    "listing_type_name": "Gratuita",
    "listing_exposure": "lowest",
    "requires_picture": false,
    "currency_id": "ARS",
    "listing_fee_amount": 0,
    "sale_fee_amount": 0,
    "free_relist": false,
    "stop_time": "2016-04-22T10:33:22.611-04:00"
}


Filter by price and category

Retrieves different listing types and each associated fee in the local currency where the item price is 5000 and the category is MLA1744.
Example:

curl -X GET https://api.mercadolibre.com/sites/:site_id/listing_prices?price=5000&category_id=MLA1744

Response:

{
    "listing_type_id": "gold_premium",
    "listing_type_name": "Oro Premium",
    "listing_exposure": "highest",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 357,
    "sale_fee_amount": 0,
    "free_relist": false,
    "stop_time": "2016-04-22T10:33:58.127-04:00"
  },
  {
    "listing_type_id": "gold",
    "listing_type_name": "Oro",
    "listing_exposure": "high",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 267,
    "sale_fee_amount": 0,
    "free_relist": false,
    "stop_time": "2016-04-22T10:33:58.135-04:00"
  },
  {
    "listing_type_id": "silver",
    "listing_type_name": "Plata",
    "listing_exposure": "mid",
    "requires_picture": false,
    "currency_id": "ARS",
    "listing_fee_amount": 147,
    "sale_fee_amount": 0,
    "free_relist": false,
    "stop_time": "2016-04-22T10:33:58.130-04:00"
  },
  {
    "listing_type_id": "free",
    "listing_type_name": "Gratuita",
    "listing_exposure": "lowest",
    "requires_picture": false,
    "currency_id": "ARS",
    "listing_fee_amount": 0,
    "sale_fee_amount": 0,
    "free_relist": false,
    "stop_time": "2016-03-23T10:33:58.132-04:00"
  }


By price and currency

Retrieves different listing types and each associated fee in the local currency where the item price is 5000 USD.

Example:

curl -X GET https://api.mercadolibre.com/sites/:site_id/listing_prices?price=5000¤cy_id=USD

Response:

{
    "listing_type_id": "gold_pro",
    "listing_type_name": "Oro Premium Full",
    "listing_exposure": "highest",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 0,
    "sale_fee_amount": 1150,
    "free_relist": false,
    "stop_time": "2016-04-22T10:34:27.793-04:00"
  },
  {
    "listing_type_id": "gold_premium",
    "listing_type_name": "Oro Premium",
    "listing_exposure": "highest",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 250,
    "sale_fee_amount": 375,
    "free_relist": false,
    "stop_time": "2016-04-22T10:34:27.779-04:00"
  },
  {
    "listing_type_id": "gold_special",
    "listing_type_name": "Oro Profesional",
    "listing_exposure": "highest",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 0,
    "sale_fee_amount": 525,
    "free_relist": false,
    "stop_time": "2016-04-22T10:34:27.782-04:00"
  },
  {
    "listing_type_id": "gold",
    "listing_type_name": "Oro",
    "listing_exposure": "high",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 150,
    "sale_fee_amount": 375,
    "free_relist": false,
    "stop_time": "2016-04-22T10:34:27.791-04:00"
  },
  {
    "listing_type_id": "silver",
    "listing_type_name": "Plata",
    "listing_exposure": "mid",
    "requires_picture": false,
    "currency_id": "ARS",
    "listing_fee_amount": 50,
    "sale_fee_amount": 375,
    "free_relist": false,
    "stop_time": "2016-04-22T10:34:27.786-04:00"
  },
  {
    "listing_type_id": "bronze",
    "listing_type_name": "Bronce",
    "listing_exposure": "low",
    "requires_picture": false,
    "currency_id": "ARS",
    "listing_fee_amount": 0,
    "sale_fee_amount": 550,
    "free_relist": false,
    "stop_time": "2016-04-22T10:34:27.788-04:00"
  },
  {
    "listing_type_id": "free",
    "listing_type_name": "Gratuita",
    "listing_exposure": "lowest",
    "requires_picture": false,
    "currency_id": "ARS",
    "listing_fee_amount": 0,
    "sale_fee_amount": 0,
    "free_relist": false,
    "stop_time": "2016-04-22T10:34:27.776-04:00"
  }


Filter by listing type and category

Retrieves listing fee associated to listing type Gold where the category id is MLA1743.
Example:

curl -X GET https://api.mercadolibre.com/sites/:site_id/listing_prices/gold?category_id=MLA1743

Response:

{
  "listing_type_id": "gold",
  "listing_type_name": "Oro",
  "listing_exposure": "high",
  "requires_picture": true,
  "currency_id": "ARS",
  "listing_fee_amount": 267,
  "sale_fee_amount": 0,
  "free_relist": false,
  "stop_time": "2016-04-22T10:35:02.225-04:00"
}


By category

Retrieves different listing types and each associated fee in the local currency where the category id is MLA1743.
Example:

curl -X GET https://api.mercadolibre.com/sites/:site_id/listing_prices?category_id=MLA1743

Response:

{
    "listing_type_id": "gold_premium",
    "listing_type_name": "Oro Premium",
    "listing_exposure": "highest",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 357,
    "sale_fee_amount": 0,
    "free_relist": false,
    "stop_time": "2016-04-22T10:35:31.996-04:00"
  },
  {
    "listing_type_id": "gold",
    "listing_type_name": "Oro",
    "listing_exposure": "high",
    "requires_picture": true,
    "currency_id": "ARS",
    "listing_fee_amount": 267,
    "sale_fee_amount": 0,
    "free_relist": false,
    "stop_time": "2016-04-22T10:35:32.006-04:00"
  },
  {
    "listing_type_id": "silver",
    "listing_type_name": "Plata",
    "listing_exposure": "mid",
    "requires_picture": false,
    "currency_id": "ARS",
    "listing_fee_amount": 147,
    "sale_fee_amount": 0,
    "free_relist": false,
    "stop_time": "2016-04-22T10:35:31.999-04:00"
  },
  {
    "listing_type_id": "free",
    "listing_type_name": "Gratuita",
    "listing_exposure": "lowest",
    "requires_picture": false,
    "currency_id": "ARS",
    "listing_fee_amount": 0,
    "sale_fee_amount": 0,
    "free_relist": false,
    "stop_time": "2016-03-23T10:35:32.003-04:00"
  }

Please rate this

Category prediction resource

The category prediction resource was created to help sellers and developers predict under which category a certain item should be listed. It’s currently working for Argentina, Bolivia, Brasil, Chile, Colombia, Costa Rica, Dominicana, Ecuador, Honduras, Guatemala, México, Nicaragua, Paraguay, Panamá, Perú, Portugal, Salvador, Uruguay and Venezuela.

Parameters

ParameterDescription
titleThe title of the item to predict. It must be a complete title in the language of the site. This parameter is mandatory.
category_fromThis parameter accepts a level 1 category, and it is used to limit the prediction to the subtree that spans from category_from to the root. This parameter is optional.
priceThe price of the item to predict. The purpose of this parameter is to provide additional information in order to improve the prediction. This parameter is optional.
seller_idSeller’s ID of the item to predict. The purpose of this parameter is to provide additional information in order to improve the prediction. This parameter is optional.

Predicting by GET

Using the GET method it’s possible to predict one item at a time:

`curl https://api.mercadolibre.com/sites/MLB/category_predictor/predict?title=Ipod%20Touch%20Apple%2016gb%205%20Gera%C3%A7%C3%A3o`


Predicting by POST

Using the POST method it’s possible to predict multiple (up to 1K) items at a time. When multiple items needs to be predicted, this method is recommended. To do this you need to send an array of JSON encoded titles and categories to predict, like in the following example:

curl -X POST -H "Content-Type: application/json" -d
'[{"title": "Ipod Touch Apple 16gb 5 Geração","category_from": "MLB1743"},{"title": "Ipod Touch Apple 16gb 5 Geração","category_from": "MLB1743"}]'
https://api.mercadolibre.com/sites/MLB/category_predictor/predict


Response fields

ParameterDescription
idId of predicted category for the item.
nameName of the predicted category.
prediction_probabilityConfidence of the prediction. This value ranges between [0, 1], values closer to zero indicate low confidence whereas values closer to 1 indicate high confidence.
path_from_rootList with the categories from the root to the leaf (the predicted category). Every category is represented by ID and NAME attributes.
variationsthis field appears only when the predicted category supports variations.
shipping_modesShipping modes supported by the predicted category.

Please rate this

Trends API is a repository of the most popular keywords in MercadoLibre.
There’s a frontend on every site where you can check the top searches by country and by category.
For example, for Argentina the url is tendencias.mercadolibre.com.ar.
You can access the rest of hispanic sites just by replacing the geographical domain.
The url for Brazil is tendencias.mercadolivre.com.br.

Resource description

keywordword users are looking for.
urllink to search results.

Hot trends by country

This API only admits GET methods and retrieves public information, so you won’t be needing an $ACCESS_TOKEN. Include {site_id} before the parameters /trends/search to look for popular keywords in a specific country.

curl -X GET https://api.mercadolibre.com/sites/{site_id}/trends/search

Hot trends by country and by category

Add {category_id} to look for popular keywords in a specific category. Remember categories belong to sites.

curl -X GET https://api.mercadolibre.com/sites/{site_id}/trends/search?category={category_id}

Limit the results

To obtain a certain amount of results, you should specify {limit} with the number of results you want to get. The maximum value is 100.

curl -X GET https://api.mercadolibre.com/sites/{site_id}/trends/search?category={category_id}&limit={limit}

Adult content

Adult content is hidden by default. If you also want to get adult keywords send the parameteradult_content=yes

curl -X GET https://api.mercadolibre.com/sites/{site_id}/trends/search?category={category_id}&limit={limit}&adult_content=yes

Please rate this

Create and manage a project

To make a better experience from your integration with MercadoLibre, we launched the Projects API resource.

Creating a new project in this resource, you could link your applications to it, provided that this app doesn’t belong to the project owner.
This help us to measure and know more about your integration.

We are going to enable a new dashboard where you will can check the performance of the different applications from your project.

Every certified developer have to create mandatorily a new project and the link to his applications.

What do I have to do?

It’s a simple concept. At first, you create a new project and then all your apps will be linked up to this.
So, you have to create just a project as integrator and put the apps in this only one.
You should do something like this, for example:
A project called MyCompanyHubIntegration with all applications related to it.
Another project called MyCompanyCustomerName and so on.

Create a project


POST: https://api.mercadolibre.com/projects?access_token=YOUR_ACCESS_TOKEN


JSON: {'name': 'Project Name', 'site_id': 'MLA'}

Expected response: 201

Add an app to your project


POST: https://api.mercadolibre.com/projects/PROJECT_ID/applications?access_token=ACCESS_TOKEN_APP_OWNER


JSON: {'application_id': APPLICATION_ID}

Expected response: 201

Get all apps from your project


GET: https://api.mercadolibre.com/projects/PROJECT_ID?access_token=ACCESS_TOKEN_PROJECT_OWNER

Delete an app from your project


DELETE: https://api.mercadolibre.com/projects/PROJECT_ID/applications?access_token=ACCESS_TOKEN_APP_OWNER


JSON: {'application_id': APPLICATION_ID}

Expected response: 200

Change a project name


PUT: https://api.mercadolibre.com/projects/PROJECT_ID?access_token=YOUR_ACCESS_TOKEN


JSON: {'name': 'changed name'}

Delete a project


DELETE: https://api.mercadolibre.com/projects/PROJECT_ID?access_token=YOUR_ACCESS_TOKEN

Please rate this

Application Manager

Get your applications

Call applications resource search with your user_id to get a detail of the applications you own.

Example:


curl -X GET https://api.mercadolibre.com/applications/search?owner_id={Owner_id}?access_token=$ACCESS_TOKEN

Response:

{
    "id": 2342346600929988,
    "site_id": "MLB",
    "name": "ML TEST",
    "description": "ML TEST APP",
    "thumbnail": null,
    "owner_id": 18731523,
    "catalog_product_id": null,
    "item_id": null,
    "price": null,
    "currency_id": null,
    "need_authorization": true,
    "short_name": "polipartes",
    "url": "http://apps.mercadolivre.com.br/polipartes",
    "callback_url": "http://www.vtexml.com.br/",
    "sandbox_mode": true,
    "is_public": true,
    "project_id": null,
    "active": true,
    "max_requests_per_hour": 18000,
    "scopes": [
      "write",
      "read",
      "offline_access"
    ],
    "domains": [
    ]
  }

Get application detail

To get the full detail about one of your apps just include the app_id on the API call.

Example:

curl -X GET https://api.mercadolibre.com/applications/213123928883922

Response:

{
  "id": 213123928883922,
  "site_id": "MLB",
  "name": "ML Test",
  "description": "ML Test APP",
  "thumbnail": null,
  "owner_id": 18731523,
  "catalog_product_id": null,
  "item_id": null,
  "price": null,
  "currency_id": null,
  "need_authorization": true,
  "short_name": "polipartes",
  "url": "http://apps.mercadolivre.com.br/polipartes",
  "callback_url": "http://www.vtexml.com.br/",
  "sandbox_mode": true,
  "is_public": true,
  "project_id": null,
  "active": true,
  "max_requests_per_hour": 18000,
  "scopes": [],
  "domains": [
  ]
}

Get applications authorized by user

To get all the applications authorized by a user just use a GET request with the user_id and the access token.

GET https://api.mercadolibre.com/users/{user_id}/applications?access_token={...}

The response would be an array of applications with the following format:

[
  - {
    "user_id": "26317316",
    "app_id": "13795",
    "date_created": "2012-12-20T15:38:27.000-04:00",
    "scopes": - [
      "read",
      "write",
    ],
   },
]

Fields description

  • user_id – The user identifier.
  • app_id – The application identifier.
  • date_created – Date when the authorization was created.
  • scopes – permissions given to the application: read, write and offline_access.

Revoke user authorization

To remove any application you must specify the application id, the user id, and the access token. Just doing a DELETE request using this query:

DELETE https://api.mercadolibre.com/users/{user_id}/applications/{app_id}?access_token={...}

The response should be:

{
	"user_id":"{user_id}",
	"app_id":"{app_id}",
	"msg":"Autorización eliminada"
}

Please rate this

Track user’s reputation

Any MercadoLibre user has a reputation level and reputation points that are calculated over the amount of transactions they had between other MercadoLibre users, the result of each one and the feedback other users gave. There’s not a public reputation resource you can work with and see the evolution of an user reputation, but since this information is stored on the User’s API you can make your system check it from time to time and save it on your database to keep a track of it during a certain period.

Just call Users API like this:
Call:

curl -X GET https://api.mercadolibre.com/users/{User_id}?attributes=seller_reputation

Response:

Response:

{
  "seller_reputation": {
    "level_id": "5_green",
    "power_seller_status": "platinum",
    "transactions": {
      "period": "historic",
      "total": 2361,
      "completed": 1602,
      "canceled": 759,
      "ratings": {
        "positive": 0.99,
        "negative": 0,
        "neutral": 0.01
      }
    }
  }
}



That’s it, now you got a detail of the user reputation at a certain date. Start store it on your system to keep a track of how the user reputation evolves.

Please rate this

Get classified items by seller id

Send the category parameter to get the classified listings of that user:

curl https://api.mercadolibre.com/sites/MLB/search?seller_id=36060987&category=MLB1743

Now you know the id of each item and you can make a call to the items resource to know more about each of them.
To improve the call you’re making we recommend you to use multiget and selection features, so you can get up to 50 products by making only one call and only the fields you’re interested in.
Call:

https://api.mercadolibre.com/items?ids={Item_id1},{Item_id2}&attributes={attribute1,attribute2,attribute3}

Example:

https://api.mercadolibre.com/items?ids=MLA599260060,MLA594239600&attributes=id,title,seller_id,price,status

Please rate this

Search products by seller

By using our public resource /sites/{site_id}/search? you can get the results of active items directly from Mercado Libre listings.

By using our private resource /users/{cust_id}/items/search?access_token= you can get a list of items posted by a certain user from his/her account.

Contents:

Get items of Listings by seller

This search adjusts to the site’s listing rules. Results will always be active items.
Notes:

  • Get Mercado Libre listing URL directly by replacing /search? for /searchUrl?
  • Offset searches above 50,000 are limited

By nickname

When you don’t know what’s the seller_id of an user by you know the nickname, you can try doing the following search:

curl https://api.mercadolibre.com/sites/MLA/search?nickname=

By seller_id

If you already know the seller_id just do as it follows:

curl https://api.mercadolibre.com/sites/MLA/search?seller_id=

Note: While the API sites/(site_id) will show item description, it will not display all the seller’s listings.

To see the full list without the descriptions, you should make the following call:

https://api.mercadolibre.com/users/{seller_id}/items/search?access_token=$ACCESS_TOKEN

By seller id for an specific category

Note that the previous searches don’t retrieve the seller’s classified listings, only their products. You can use the following example to search within a specific category and this call accepts classified categories to also query those listings.

curl https://api.mercadolibre.com/sites/MLB/search?seller_id=36060987&category=MLB1743

Now you know the id of each item of a seller you can make a call to the items resource to know more about them.
To improve the call you’re making we recommend you to use multiget and selection features, so you can get up to 50 products by making only one call and only the fields you’re interested in.

Call:

https://api.mercadolibre.com/items?ids={Item_id1},{Item_id2}&attributes={attribute1,attribute2,attribute3}

Example:

https://api.mercadolibre.com/items?ids=MLA599260060,MLA594239600&attributes=id,title,seller_id,price,available_quantity,status

Response:

{
	"available_quantity": 24,
	"id": "MLA594239600",
	"price": 1999,
	"seller_id": 143125485,
	"status": "active",
	"title": "Celular Libre Samsung Galaxy Ace 4 Neo Blanco"
  },
  {
	"available_quantity": 5,
	"id": "MLA599260060",
	"price": 7999,
	"seller_id": 167520920,
	"status": "active",
	"title": "Aire Acondicionado Split Rca Frio Calor 3400w"
  }

Filter and sort search results in the listings

In /sites/{site_id}/search? you will find the fields ”available_sorts” and “available_filters”.

How to filter?
For example, to filter items with free shipping, you will find the “shipping” ID among the ”available_filters” with “free” ID value.

https://api.mercadolibre.com/sites/MLA/search?seller_id={cust_id}&shipping=free


How to sort?
In this case, you should add “sort” to the available sort ID that you wish to apply, for example: “price_asc”

https://api.mercadolibre.com/sites/MLA/search?seller_id={cust_id}&sort=price_asc

Note: Listing search includes an order of relevance defined by default.

Get items from a seller’s account

This search is performed directly in the seller’s account; this is a private resource and you will need an access_token.

Note: Note that using this call, you will get a list of items. For more information on each item, we suggest using a multiget as explained before.

By seller_id

If you already know the seller_id, just do the following:

curl https://api.mercadolibre.com/users/{seller_id}/items/search?access_token=$ACCESS_TOKEN

By SKU

If the item has an SKU in the “seller_custom_field” you can look for it as follows:

curl https://api.mercadolibre.com/users/{Cust_id}/items/search?sku={seller_custom_field}&access_token=$ACCESS_TOKEN

By status

curl https://api.mercadolibre.com/users/{Cust_id}/items/search?status=active&access_token=$ACCESS_TOKEN

Filter and Sort results of items by seller

In /users/{cust_id}/items/search? you will find the fields ”available_orders” and “available_filters”

How to sort?
In this case, you should add “orders” to the available sort ID that you wish to apply, for example: “start_time_desc”

https://api.mercadolibre.com/users/226384143/items/search?orders=start_time_desc&access_token=$ACCESS_TOKEN

Note: It includes a stop_time_asc by default.

How to filter?
For example, to filter items with listing_type “gold_pro” you will find the “listing_type_id” among the “available_filters” with the “gold_pro” ID value.

https://api.mercadolibre.com/users/{Cust_id}/items/search?isting_type_id=gold_pro&access_token=$ACCESS_TOKEN


For more search examples, go to: Items and searches.

Please rate this

Working with pictures

Pictures are optional when listing an item, but they sure make a big difference in terms of quality and it will improve your possibilities of selling by attracting more visits to your items. When you list a new item, you can add pictures at that moment. This tutorial shows how to upload pictures to our servers and add them on your items.

Contents:

Considerations & Best Practices

RGB pictures are highly recommended over CMYK pictures.
There is um maximum imagens per item allowed to publish according to the category.
You’re allowed to upload pictures up to 10 MB in the following formats:

  • JPG
  • JPEG
  • PNG
  • not animated GIF

Zooming

For pictures wider than 800 pixels, a zoom widget is activated so when buyers roll over they can take a close-up look. This is highly recommended for Clothes and Real Estate properties.
Upload a picture
Now is the time to upload your first image file to be stored on our servers. This is really easy to do, just take note of the exact path where you have your image saved:

curl -F file=@/home/user/picture.jpg

https://api.mercadolibre.com/pictures?access_token=$ACCESS_TOKEN



As a response you’ll get a JSON describing the picture details.
Remember to keep the picture id. The other fields represent different picture sizes.

{
   "id":"MLA430387888_032012",
   "quality":"",
   "variations":[...]
}


Link a picture to your Item

Using the picture_id obtained before you can link the picture to your item, like this:

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d
'{"id":"MLA430387888_032012"}'

https://api.mercadolibre.com/items/MLA421101451/pictures?access_token=$ACCESS_TOKEN



That’s all! Go to your item’s description page (using the permalink field) and check how your picture displays.

Replace pictures

If you need to replace the current pictures of an item, you need to make a PUT including the Item ID and the picture url, with your access_token like in the example that follows:

curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
'{
  "pictures":[
    {"source":"http://www.apertura.com/export/sites/revistaap/img/Tecnologia/Logo_ML_NUEVO.jpg_33442984.jpg"},
    {"source":"http://appsuser.net/www/wp-content/uploads/2012/10/logo-mercadolibre.jpg"}
  ]
}' https://api.mercadolibre.com/items/{item_id}?access_token=$ACCESS_TOKEN



Great! now the new picture will be showing on your item. Now you know how to add or replace pictures, remember good pictures will attract more buyers!

Please rate this

Item description

An item description contains custom information about the item you are selling. You decide how much information you add on the item description and how is going to be displayed. You can choose between a simple plain text description or you can make a custom HTML template.
The information displayed on the description should complement the item attributes we already display on the item description page. For example you can add specifications, images, sale details, promotional ads, everything you find useful and catchy for buyers to choose your product, and reduce the need of making many questions before making an offer.

Contents:

Considerations & Best Practices

Description can be an HTML, but notice that there are some elements that will be blocked or replaced for company politics and security reasons.

Elements you should avoid

  • Iframes
  • Scripts
  • Froms
  • Inputs
  • Meta
  • Object
  • Embed


Elements that can be cleaned

  • Styles (for example: position-absolute)
  • Attributes
  • Ids
  • Javascript inline

Add or replace current description

If you didn’t send anything on the description when you listed your product, you can use this tutorial to add it later on, just follow this example:
Example:

curl -X PUT -H "Cot: application/json" -d

'{ 
"text":"Test."
}'

https://api.mercadolibre.com/items/{ITEM_ID}/description?access_token=$ACCESS_TOKEN


See?, Easy! Description can be added or replaced whenever you want, even when the item has bids already, so get to work and make a great description for your items.

Please rate this

Listing validator

Since we know sometimes you won’t get your listing done in just one try, we offer you the possibility to check if your listing is exactly the way you want it before publishing. The Items API provides a validation service to check your listing details before publishing. Use it to practice until you get it right!

Contents:

Validation examples

Let’s see an example of how it works. Suppose you send this Json:

Example:

{
"seller_id":,
"id",
"price":"p",
"seller_contact":null,
"pictures": [[1,2,3]] 
}

Make POST to this url:

https://api.mercadolibre.com/items/validate?access_token=$ACCESS_TOKEN

You’ll get an output describing exactly the improvements you need to make on your Json in order to successfully list an item:

{
"message":"body.invalid_field_types",
"error":"[invalid property type: [price] expected Number but was String value: p,
invalid property type: [seller_contact] expected Map but was Null value: null,
invalid property type: [pictures[0]] expected Map but was JSONArray value: [1, 2, 3],
invalid property type: [seller_id] expected Number but was String value: id]",
   "status":400,
   "cause":[

   ]
}

 

Validate your item

 

curl -X POST -H "Content-Type: application/json" -d'{
  "title":"Teacup",
  "category_id":"MLA1902",
  "price":10,
  "currency_id":"ARS",
  "available_quantity":1,
  "buying_mode":"buy_it_now",
  "listing_type_id":"bronze",
  "condition":"new",
  "description": "Item:, Teacup Model: 1. Size: 5cm. Color: White. New in Box",
  "video_id": "YOUTUBE_ID_HERE",
  "pictures":[
    {"source":"http://upload.wikimedia.org/wikipedia/commons/e/e9/Tea_Cup.jpg"}
  ]
}' https://api.mercadolibre.com/items/validate?access_token=$ACCESS_TOKEN

 

Validate an item with variations

 

curl -X POST -H "Content-Type: application/json" -d '{
   "title":"Short",
   "category_id":"MLA126455",
   "price":10,
   "currency_id":"ARS",
   "buying_mode":"buy_it_now",
   "listing_type_id":"bronze",
   "condition":"new",
   "description": "Short with variations", 
   "variations":[
      {
      "attribute_combinations":[
        {
          "id":"93000",
          "value_id":"101993"
        },
        {
          "id":"83000",
          "value_id":"91993"
        }
      ],
      "available_quantity":1,
      "price":10,
      "picture_ids":[
          "http://bttpadel.es/image/cache/data/ARTICULOS/PROVEEDORES/BTTPADEL/BERMUDA%20ROJA-240x240.jpg"
      ]
      },
      {
      "attribute_combinations":[
        {
          "id":"93000",
          "value_id":"101995"
        },
                {
          "id":"83000",
          "value_id":"92013"
        }
      ],
      "available_quantity":1,
      "price":10,
      "picture_ids":[
          "http://www.forumsport.com/img/productos/299x299/381606.jpg"
      ]
      }
   ]
}' https://api.mercadolibre.com/items/validate?access_token=$ACCESS_TOKEN

 

Validate your real estate item

 

curl -X POST -H "Content-Type: application/json" -d' { 
  "site_id": "MLA",
  "title": "Propiedad en Alquiler, Item de Testeo, Por favor, no ofertar",
  "category_id": "MLA52745",
  "price": 5000,
  "currency_id": "ARS",
  "available_quantity": 1,
  "buying_mode": "classified",
  "listing_type_id": "silver",
  "condition": "not_specified",
  "pictures": [
    {
      "source":"http://farm3.staticflickr.com/2417/2176897085_946b7b66b8_b.jpg"
    },
    {
      "source":"http://farm2.staticflickr.com/1056/628680053_3b7c315548_b.jpg"
    }
  ],
  "seller_contact": {
    "contact": "Pepe",
    "other_info": "Additional contact info",
    "area_code": "011",
    "phone": "4444-5555",
    "area_code2": "",
    "phone2": "",
    "email": "contact-email@somedomain.com",
    "webmail": ""
  },
  "location": {
    "address_line": "My property address 1234",
    "zip_code": "1111",
    "neighborhood": {
      "id": "TUxBQlBBUzgyNjBa"
    },
    "latitude": -34.48755,
    "longitude": -58.56987,
  },  
  "attributes": [
    {
      "id": "MLA50547-AMBQTY",
      "value_id": "MLA50547-AMBQTY-1"
    },
    {
      "id": "MLA50547-ANTIG",
      "value_id": "MLA50547-ANTIG-A_ESTRENAR"
    },
    {
      "id": "MLA50547-MTRS",
      "value_name": "500"
    },
    {
      "id": "MLA50547-SUPTOTMX",
      "value_name": "2000"
    },
    {
      "id": "MLA50547-BATHQTY",
      "value_id": "MLA50547-BATHQTY-1"
    },
    {
      "id": "MLA50547-DORMQTYB",
      "value_id": "MLA50547-DORMQTYB-3"
    },
    {
      "id": "MLA50547-EDIFIC",
      "value_id": "MLA50547-EDIFIC-CHALET"
    }
  ],
   "description" : "This is the real estate property description."
}' https://api.mercadolibre.com/items/validate?access_token=$ACCESS_TOKEN

 

Error codes reference

You will receive a “HTTP/1.1 204 No Content” if the JSON is correct to listing or the corresponding error as we saw before in the example.
Note: To see the “HTTP/1.1 204 No Content” using curl you have to add the -i parameter.

Considerations

This validation process is not mandatory, but will most likely come handy when testing your APP. Keep in mind that there is no sandbox nor pre-production environment, so every item listed during your testing phase will be visible for every user that navigates our marketplace. Please check our Testing tutorial to know about particularities and best practices while you’re starting.

Please rate this

Paging results

Overview

You can define the page size of the result list. There are 2 parameters: Limit and Offset. Both parameters define the size block of the results. This article is based on the search example, but you can use paging on every resource that presents on its response information about “paging”, like follows:

.....
  "paging": {
    "total": 285,
    "offset": 0,
    "limit": 50,
  }
  .....



range-slider

Contents:

  • Default values
  • Limit
  • Offset
  • Define a range of results

Default values

Default values are offset=0 and limit=50.

curl https://api.mercadolibre.com/sites/MLA/search?q=ipod nano



In the paging section of the JSON response, you can see the total number of items that match the search and the offset value with the default limit applied.

.....
  "paging": {
    "total": 285,
    "offset": 0,
    "limit": 50,
  }
  .....


Limit

To reduce the page size you can change the limit parameter. For example, if you are interested in retrieving just the first 3 items:

curl https://api.mercadolibre.com/sites/MLA/search?q=ipod nano&limit=3



This action retrieves a JSON data with an array of 3 items as shown:

{
  "site_id": "MLA",
  "query": "ipod nano",
  "paging": {
    "total": 284,
    "offset": 0,
    "limit": 3,
  },
  "results": [
    {...},
    {...},
    {...},
  ],
  "sort": {...},
  "available_sorts": [...],
  "filters": [...],
  "available_filters": [...],
}


Offset

By using the offset attribute, you can move the lower limit of the result block. For example, if you are interested in retrieving the 50 items that follow the default response:

curl https://api.mercadolibre.com/sites/MLA/search?q=ipod nano&offset=50
{
  "site_id": "MLA",
  "query": "ipod nano",
  "paging": {
    "total": 285,
    "offset": 50,
    "limit": 50,
  },
  "results": [...],
  "sort": {...},
  "available_sorts": [...],
  "filters": [...],
  "available_filters": [...],
}



This response retrieves 50 items starting from the first fifty items.

Define a range of results

It is possible to combine both parameters. You can retrieve items from the third to the sixth item in the original search result:

curl https://api.mercadolibre.com/sites/MLA/search?q=ipod nano&offset=3&limit=3



This action retrieves a JSON data with an array of 5 items as shown:

{
  "site_id": "MLA",
  "query": "ipod nano",
  "paging": {
    "total": 285,
    "offset": 3,
    "limit": 3,
  },
  "results": [
    {...},
    {...},
    {...},
  ],
  "sort": {...},
  "available_sorts": [...],
  "filters": [...],
  "available_filters": [...],
}


Please rate this

Search items by category

Overview:

The search operation returns items which belong to a MercadoLibre item’s category.
For more details about categories and the category hierarchy, see the guide Categories API.

Contents:

  • Request
  • Response
  • Request

By using a MercadoLibre item’s category, you can retrieve a list of items which belong to it. If you are interested in defining a block size response, read the search paging article.

curl https://api.mercadolibre.com/sites/MLA/search?category=MLA5726

 

Response

The search responses an array of results of items inside the category. You’ll find most of the item’s attributes on the result.

{
  "site_id": "MLA",
  "paging": {
    "total": 109720,
    "offset": 0,
    "limit": 50
  },
  "results": [
    {
      "classified_marc_attribute_code": "-MARC",
      "classified_mode": "classified",
      "accepts_mercadopago": true,
      "address": null,
      "attributes": [
      ],
      "available_quantity": 10,

 

Use OPTIONS http method to get a JSON encoded response that will describe the API, with all the allowed methods and connections between another part of the API. It is a standard format to get API documentation.

Please rate this

Server side

This guide explains how to perform the authentication/authorization flow on the Server Side, which is better suited for applications executing server side codes, such as, applications developed in Java, Grails, Go, etc.
The Open Platform team recommends using our SDKs since their functionality will streamline the authorization flow using the OAuth protocol.

Contents:

Step by Step

These are the steps for the Server Side OAuth:

  • To begin, you will need the app ID and the secret key obtained when you created your application. If you have not done it yet, this guide provides the necessary steps.

  • When starting the authorization flow, your application should redirect users to Mercado Libre so that they can authenticate and subsequently grant permission to your application. You just need to redirect users to URL:

https://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=App_id

Note: In this example we use the URL for Argentina (MLA), if you are working with other countries, remember to change the .com.ar for the relevant country’s domain.
To see the countries where Mercado Libre operates, enter the next URL http://www.mercadolibre.com/

Parameters

response_type: code – It indicates that the intended operation is to obtain an authentication code that will enable your server to interact with Mercado Libre.
client_id: It is the App ID assigned to your app when created.
redirect_uri: URL – It is your server URL configured for your application.
Note: Remember that if you are working in a local host you can use http, but if you are working in a public domain you must use http and a less than 5 digit port.
No need to worry about authentication of users in Mercado Libre, our platform will take care of that!

  • Once the user completes the authentication process, he/she will be redirected to your application authorization page. The user will be presented with all the requested permits there, along with your app description.
  • captura-de-pantalla-2016-09-29-a-las-3-25-09-p-m

  • When permissions are granted, the user will be redirected to the Redirect URI (configured for your Mercado Libre application) and parameter used in the authentication URL with authorization code under:
http://YOUR_REDIRECT_URI?code=SERVER_GENERATED_AUTHORIZATION_CODE


  • The authorization code is used to exchange it for the access_token (an access key to private resources valid for 6 hours). To obtain the token, you must do the following POST:
https://api.mercadolibre.com/oauth/token?grant_type=authorization_code&client_id=APP_ID&client_secret=SECRET_KEY&code=SERVER_GENERATED_AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

Response:

{
	"access_token" : "APP_USR-6092-3246532-cb45c82853f6e620bb0deda096b128d3-8035443",
	"token_type" : "bearer",
	"expires_in" : 10800,
	"scope" : "write read"
}

Parameters

grant_type: authorization_code – It indicates that the intended operation is to exchange the “code” for an access_token.
client_id: It is the APP ID of the application you created.
client_secret: hash – The Secret Key generated for your application when created.
code: The authorization code obtained in the previous step.
redirect_uri: URL – The redirect URI configured for your application or one of the allowed domains.

  • Done! As you can see, you will have the access_token in the response to call our API and thus gain access to the user’s private data.
    For example, to access the user’s private information:
$ curl https://api.mercadolibre.com/users/me?access_token=$ACCESS_TOKEN

Response:

{
    "id": 178553776,
    "user_id": 206946886,
    "contact": null,
    "phone": null,
    "address_line": "Triunvirato 5555",
    "floor": null,
    "apartment": null,
    "street_number": "5555",
    "street_name": "Triunvirato",
    "zip_code": "1414",
    "city": {
      "id": "TUxBQlZJTDcwOTla",
      "name": "Villa Urquiza"
    },
    "state": {
      "id": "AR-C",
      "name": "Capital Federal"
    },
    "country": {
      "id": "AR",
      "name": "Argentina"
    },
    "neighborhood": {
      "id": null,
      "name": null
    },
    "municipality": {
      "id": null,
      "name": null
    },
    "search_location": {
      "state": {
        "id": "TUxBUENBUGw3M2E1",
        "name": "Capital Federal"
      },
      "city": {
        "id": null,
        "name": null
      },
      "neighborhood": {
        "id": null,
        "name": null
      }
    },
    "types": [
    ],
    "comment": "",
    "geolocation_type": "ROOFTOP",
    "latitude": -34.5676878,
    "longitude": -58.4933182,
    "status": "active",
    "date_created": "2016-02-24T16:29:59.000-04:00",
    "normalized": true,
    "open_hours": {
      "on_holidays": {
        "hours": [
        ],
        "status": "closed"
      }
    }
  }


  • Nothing lasts forever, not even our access_token. It will expire 6 hours after it was requested.



What happens if I need to work with an access_token for more than 6 hours?
If your app has the option offline_access selected, you will receive a refresh_token along with the access_token as shown before; you should save the refresh_token to be later exchanged for a new access_token upon expiration.
To refresh your access_token you need to make the following POST.

https://api.mercadolibre.com/oauth/token?grant_type=refresh_token&client_id=APP_ID&client_secret=SECRET_KEY&refresh_token=REFRESH_TOKEN

Parameters

grant_type: refresh_token – It indicates that the intended operation is to refresh a token.
refresh_token: The refresh token from the approval step.
client_id: The client ID of your application.
client_secret: The Secret Key generated for your app when created.

Response:

{
    "access_token" : "APP_USR-6092-3246532-cb45c82853f6e620bb0deda096b128d3-8035443",
	"token_type" : "bearer",
	"expires_in" : 10800,
	"refresh_token" : "TG-5005b6b3e4b07e60756a3353",
	"scope" : "write read offline_access"
}

The response includes the original access_token validated for 6 hours and a new refresh token.

This action will be repeated every time an access_token expires so remember to save the new refresh_token.

Server-Side Flow

In short, this is the process you will be performing:

flujo_serverside_eng

References:
1) Redirect users to Mercado Libre.
2) No need to worry about authentication of users in Mercado Libre, our platform will take care of that!.
3) Authorization page.
4) API call Mercado Libre POST to exchange the authorization code for an access token.
5) API Mercado Libre exchanged the authorization code for an access token.
6) You can now use the access_token to call our API and thus gain access to the user’s private data.

a- Redirect

https://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=APP_ID&redirect_uri=REDIRECT_URL

b-

GET
http://YOUR_REDIRECT_URI?code=SERVER_GENERATED_AUTHORIZATION_CODE

c-

POST
https://api.mercadolibre.com/oauth/token?grant_type=authorization_code&client_id=APP_ID&client_secret=SECRET_KEY&code=SERVER_GENERATED_AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

d- Response:

{
  "access_token" : "APP_USR-6092-3246532-cb45c82853f6e620bb0deda096b128d3-8035443",
  "token_type" : "bearer",
  "expires_in" : 10800,
  "scope" : "write read"
}

FAQs

Interact with community developers and share your doubts and experiences.

Please rate this

Client Side

This guide explains how to perform authentication/authorization flow on the Client Side, which is better suited for applications executing client side codes, such as, applications developed in javascript/ajax, Angular, mobile applications, among others.
MELI developers recommend using our SDKs since their functionality will streamline the authorization flow using the OAuth protocol.

Contenidos

Step by Step

These are the steps for the oAuth Client Side:

  • To begin, you need the app_id obtained when you created your application. If you have not done it yet, this guide provides the necessary steps.

  • When starting the authorization flow, your application should redirect users to Mercado Libre so that they can authenticate and subsequently grant permission to your application. You just need to redirect users to URL:

https://auth.mercadolibre.com.ar/authorization?response_type=token&client_id=App_id

Note: In this example we use the URL for Argentina (MLA), if you are working with other countries, remember to change the .com.ar for the relevant country’s domain.
To see the countries where Mercado Libre operates, enter the next URL http://www.mercadolibre.com/.

Parameters

response_type: token – It indicates that the intended operation is to obtain a token that will enable your application to interact with Mercado Libre.
client_id: It is the App ID assigned to your application when created. No need to worry about authentication of users in Mercado Libre, our platform will take care of that!

  • Once the user logs in, he/she will be redirected to your application authorization page. The user will be presented with every requested permit there.

  • When permissions are granted, the user will be redirected to the Redirect URI (configured for your Mercado Libre application) with the relevant access_token attached to the URL, as follows:
http://YOUR_URL#access_token=APP_USR-6092-3246532-cb45c82853f6e620bb0deda096b128d3-8035443&expires_in=10800&user_id=USER_ID&domains=APP_DOMAINS

Parameters

access_token: Access key to private resources.
Expires_in: Access token service life in seconds.
Domains: Redirect URI domain.

  • Done! You can now use the access_token to call our API and thus gain access to the user’s private data.
    For example, to access the user’s private information:
$ curl https://api.mercadolibre.com/users/me?access_token=$ACCESS_TOKEN

Response:

http://developers.mercadolibre.com/usuarios-y-aplicaciones/#modal2

Notes:

  • Remember that if the access_token expires you will have to go over the previous steps to obtain a new one.
  • When using this flow, you cannot get a refresh token. Once the token expires, you will need to redirect the user once again to the authorization URL to obtain the new access token.

Client-Side Flow

In short, this is the process you will be performing:
flujo_clientside_eng
References:
1) Redirect users to Mercado Libre.
2) No need to worry about authentication of users in Mercado Libre, our platform will take care of that!.
3) Authorization page.
4) You can now use the access_token to call our API and thus gain access to the user’s private data.

a-

POST 
https://auth.mercadolibre.com.ar/authorization?response_type=token&client_id=App_id

Remember to change the .com.ar for the relevant country’s domain.

b-

GET
http://YOUR_URL#access_token=APP_USR-6092-3246532-cb45c82853f6e620bb0deda096b128d3-8035443&expires_in=10800&user_id=USER_ID&domains=APP_DOMAINS

FAQs

Interact with community developers and share your doubts and experiences.

Please rate this