Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 12/07/2024

Vehicle Package Management

In vehicles, to publish a listing, the seller needs to have a publication package contracted with Mercado Livre. This contracting is done directly with the commercial team. Advertisement packages are used to display vehicles. They have monthly, quarterly, semiannual, and annual durations, with automatic renewal, meaning they are renewed periodically to keep listings visible. With the package allocated, both the seller and the integrator are ready to publish, either via API or through our platform. The type of package is represented by the listing_type field of the listing.

Nota:
For testing purposes, you should send the test user to the support channel to activate it as car dealer and assign to a publishing package.

Package types

There are 2 types of packages:
Publication package: mandatory for the seller to make publications. This is the Silver package, that is, listing_type = silver.
Featured package: this package is optional; The seller uses it to increase the exposure of their publications. It can be Gold (listing_type = gold) or Premium Gold (listing_type = gold_premium).
These two packages offer fees that are consumed with each advertisement published (in the case of a publication package) and each time an update / highlight is made (in the case of an featured package).
Currently, each user must contract the publications and featured packages through a Mercado Libre account executive. This action is not possible through the API.
The listing_type used to publish an ad will always be the lowest: "Silver", and, in case you want to highlight the publication, it will be necessary to update it with the desired listing_type (which consumes a quota in the featured package).
Remember that in GET calls to the classifieds_promotion_packs API resource, you can use the package_content parameter to know which package you want to check:

Parameter: package_content
Mandatory: No
Default: publications
Type: String
Values: package type:

  • publications - publication packages
  • upgrades - featured packages
  • developments - vehicle entrepreneurship packages
  • ALL - returns all available packages

A customer must necessarily have a listing package to advertise,but featured packages are optional. The customer can also have more than one active package simultaneously. Each active package has its own fees, due dates, etc.
To know how to send a publication, learn our List vehicles, and remember: the advertisement must first be sent and published with a listing package, and then updated as a featured package.


Query packages by category

To query the packages available for the classified categories, it is first necessary to know which category will be used and from which site. For example, in Brazil, the category of vehicles is MLB1743.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/{category_id)/classifieds_promotion_packs

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/MLB1743/classifieds_promotion_packs

Response:

[
  {
    "id": "PUS30FREE",
    "category_id": "MLB1459",
    "brand": "MLREALESTATE",
    "description": "Todo o seu estoque",
    "price": 0,
    "package_type": "unlimited",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "free",
    "max_upgrades": 0,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 100000
      }
    ]
  }
]

Query listing packages engaged by a user

This query is important, because through it it is possible to know what packages a client has and what is the number of ads available in each one, by entering the user id (client), the type of package (package content) and the token . Here is an example call.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs?package_content=$PACKAGE_CONTENT

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/135146148/classifieds_promotion_packs?package_content=ALL

Response:

[
    {
     "id": 754985,
     "user_id": "135146148",
     "promotion_pack_id": "MPAB",
     "category_id": "MLU1743",
     "description": "Paquete 15 Básico",
     "package_type": "rotary",
     "package_content": "publications",
     "status": "active",
     "date_created": "2013-05-23T15:34:48.498-04:00",
     "date_start": "2013-05-23T15:34:47.544-04:00",
     "date_expires": "2013-06-22T15:34:47.544-04:00",
     "date_stopped": null,
     "last_updated": "2013-05-23T15:35:48.211-04:00",
     "engagement_type": "none",
     "charge_id": 822129921,
     "remaining_listings": 15,
     "used_listings": 0,
     "listing_details": [
        {
           "listing_type_id": "silver",
           "available_listings": 15,
           "used_listings": 0,
           "remaining_listings": 15
        }
     ]
    }
]

Look at the status = active field; through it, it is only possible to verify the plans that are still active. Through the package_content, it is possible to verify if the package is published (publications) or highlighted (upgrades). Finally, through the remaining_listings field, it is possible to know how many publications the client still has available. This is important, you will see in your system how many packages the customer has and the number of ads he has left to publish and highlight, before sending a publication to Mercado Libre.


Resource description

Attribute Description
id Unique package identifier.
user_id Unique id of the user who engaged the package.
category_id Package category.
description Package name.
package_type Package detail.
status Package status possible values are: active: the user can use this package to list. An available_listing will be discounted when he does. pending: the package it’s not active yet. finished: expired package.
date_created Date the package was created.
date_start Date the package was activated.
date_expires Date the package expires.
date_stopped Date the package was finished.
last_updated Last time the package was updated.
engagement_type Possible values are: “none”: The package was engaged for one time. “re-engagement”: When the package expires, a similar package_type will be re engaged automatically.
charge_id Unique id of the charge generated over the engagement of the package.
listing_details Detailed information about listing types and availability.
listing_type_id listing_type associated to the package.
available_listings Amount of listings the user gets with the package.
used_listings Already spent listings.
remaining_listings Available listings left.

Verify if a user has a specific listing_type available

This is a faster way to know if the user has a specific listing_type.


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs/silver

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/135146148/classifieds_promotion_packs/silver

Item stand-out

To stand out a listing you should make the following post. Bear in mind that in order to perform this action, the user should have previously engaged a stand-out package:


Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/{item_id}/listing_type

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA111111111/listing_type -d '{"id":"gold_premium"}'

In the previous example, the list is being updated to listing type = gold_premium (Premium Gold). Remember also that no charge is generated when making this call and that, in case the update is undone, the outstanding quota becomes available again. Also isn´t it possible to highlight a publication without at least one featured package being hired.


Validity time of the publication

Important:
This condition applies to cars and motorcycles, published by professional users (user_type: car_dealer).

There is a maximum life cycle time for the item. That is, for an item to be published, it will depend on two main conditions:

  • That you have an active quota of the corresponding publishing package;
  • Which is within the expected life cycle.


  • For cars for sale and motorcycles for sale, the API will finalize the item after xx days of publication, applying the cycle rule shown in the table above.

    Significance of the item life cycle time parameters for cars and motorcycles:

    start_time: The API defines it at the time of creating the item.

    stop_time: The API defines at the time of creating the item following the category.

    expiration_time: The API defines at the time of creating the item according to the duration of the promotion package (active publishing package you have).


    When the item reaches the stop_time, the API will close the item, the status of the item will change from active to closed with the sub-status expired.


    When the package is active and the item is discarded by closed/sub_status: expired, it may be because the life cycle of the item has come to an end. The integrator can check the start_time of the item to confirm this or not.


    Exemple:

    Un ítem auto en venta (category MLC157522) that was posted with:

    start_time: 2022-01-01T00:06:15.000Z

    stop_time: 01/06/2022T00:06:15.000Z

    expiration_time: 2022-02-01T00:06:15.000Z (expiration of the monthly publication package)


    It was published on 01/01/2022 and will remain active as long as the publication package is active and within the life cycle (180 day life cycle as it is a sale). On 06/01/2022, the item will be closed.


    Rules for Automatic Renewal of Packages with Automatic Re-engagement

    Packages perform a series of validations to renew an engagement-type "re-engagement" package:

    • The package must not be paused.
    • The user must be enabled to publish (verify status.list.allow=true).
    • The user must not have debts (check if status.list.codes and status.list.immediate_payment.reasons are set to "has_debt").

    How to cancel automatic renewal of highlights?

    Currently, this cancellation is not done via the API. The seller/store user must go to their Mercado Libre account > Then, click on the Summary section. Next, uncheck the package renewal option, confirm, and you're done.


    Next: List vehículos.