Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 07/02/2024

Campaigns with installments

f
Important:
Important: Please note that from now on, your listings will be differentiated by the installment plans you add. So that you can easily identify what your listings offer, they are no longer called "Classic" or "Premium". Ver más.

We currently have a new installment plan applicable to your Mercado Shops channel listings, in which you are able to choose to list with or without installments.
With the "Classic" listing (gold_special) , you offer installments with interest rate at your buyers' expense, allowing them to select the installment options they prefer. On the other hand, if you choose the Premium listing (gold_pro), you offer the best installment plan at your expense. When creating or editing your listing, you can choose the number of installments you want to offer. To find the costs for offering installments in addition to the selling fee, please check this table.

*The campaigns apply exclusively to sales on the Mercado Shops channel.


Listings in which you choose not to add installments

Installments with low interest rate: with this option you'll pay a 4% fee for offering your buyers payments in three to twelve installments with a lower interest rate than the banks. This way you can offer more competitive prices. To do so, please edit your listings and activate it with the tag "mshops_pcj-co-funded".



Listings in which you choose to add installments

Three installments at the same price you list: you can choose to offer payments in three installments at the same price you list and pay less selling fees on your Mercado Shops* store. This way you can offer more competitive prices. To do so, edit your listings and activate the mshops_3x_campaign option. This campaign will be available to all sellers and in selected categories.

  • Cuota Simple 3: listings from Argentina eligible to participate in the "Cuota Simple 3" program. This way, customers can buy your products in three installments at the same price you listed and you can offer more competitive prices. To do so, please edit your listings and activate the "mshops_cuota-simple-3" option.
  • Cuota Simple 6: listings from Argentina eligible to participate in the "Cuota Simple 6" program. This way, customers can buy your products in six installments at the same price you listed and you can offer more competitive prices. To do so, please edit your listings and activate the "mshops_cuota-simple-6" option.

The campaigns apply exclusively to sales on the Mercado Shops channel. Check costs to add installments.



Comparison between installment plans

Listings in which you choose not to add installments

Campaign name listing_type Tag Marketplace Tag Mshops
I don't want to add installments (seller doesn't have the "Cuota Simple" program enabled). gold_special No tag No tag
I don't want to add installments (seller has the "Cuota Simple" program enabled). gold_special cuota-simple-paid-by-buyer Doesn't apply
Three to twelve installments with low interest rate. gold_special pcj-co-funded mshops_pcj-co-funded

Listings in which you choose to add installments

Campaign name listing_type Tag Marketplace Tag Mshops
Three installments at the same price you listed. gold_pro 3x_campaign mshops_3x_campaign
Six installments at the same price you listed. gold_pro No tag Doesn't apply
Three installments at the same price you listed - "Cuota Simple" program. gold_pro cuota-simple-3 mshops_cuota-simple-3
Six installments at the same price you listed - "Cuota Simple" program. gold_pro cuota-simple-6 mshops_cuota-simple-6


Enabled users for campaigns

Perform a GET to the feature "/special_installments/mshops_cuota-simple-6" ("cuota-simple-3" campaign or "mshops_cuota-simple-6") as applicable, with "$SELLER_ID". If the user can participate in the campaign, the date when they were enabled will be displayed.

Note:
For mshops_3x_campaign and mshops_pcj-co-funded campaigns, this doesn't apply, since all sellers can participate with no limitations.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/special_installments/mshops_cuota-simple/sellers/$SELLER_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/special_installments/mshops_cuota-simple-6/sellers/1234

Response:

{
   "date_created":"2019-08-30T16:09:10.941-04:00",
   "seller_id":1234
}

If the user is not allowed to offer up to six installments, the result of the previous query is the following: 

{
   "message": "seller does not exist",
   "error": "seller.not_found",
   "status": 404,
   "cause": []
}


Selling fees per campaigns

To check the selling fees, you must perform a GET to the feature /listing_prices filtering by price, listing_type, tag and domain, as applicable.

Please remember to:

  1. Respetar la relación listing_type+tag (ver opciones) .
  2. Filter per channel to check all the specific fees. Otherwise, you will view the ones from the marketplace by default.

Example of the "Notebooks" domain:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/listing_prices?price=10000&listing_type_id=gold_pro&tags=3x_campaign&domain_id=MLA-NOTEBOOKS

Response of the "Three installments at the same price you listed" campaign:

[
    {
        "currency_id": "ARS",
        "free_relist": false,
        "listing_exposure": "highest",
        "listing_fee_amount": 0,
        "listing_fee_details": {
            "fixed_fee": 0,
            "gross_amount": 0
        },
        "listing_type_id": "gold_pro",
        "listing_type_name": "Premium",
        "requires_picture": true,
        "sale_fee_amount": 1983,
        "sale_fee_details": {
            "financing_add_on_fee": 15,
            "fixed_fee": 0,
            "gross_amount": 1983,
            "meli_percentage_fee": 4.83,
            "percentage_fee": 19.83
        },
        "stop_time": "2043-09-14T00:00:00.000-04:00"
    }
]

That is, in the "Notebooks" domain with the 3x_campaign, tag, the selling fee on Mercado Shops will be 4.83%, and the fee for offering payments in installments will be 15%, total fee of 19.83%. For more information, check resources to find the selling costs.


Example of the "Notebooks" domain for the Mercado Shops channel with three to twelve installments with low interest rate:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/listing_prices?price=10000&listing_type_id=gold_special&tags=mshops_pcj-co-funded&channel=mshops&domain_id=MLA-NOTEBOOKS

Response of the "Three to twelve installments with low interest rate": 

[
    {
        "currency_id": "ARS",
        "free_relist": false,
        "listing_exposure": "highest",
        "listing_fee_amount": 0,
        "listing_fee_details": {
            "fixed_fee": 0,
            "gross_amount": 0
        },
        "listing_type_id": "gold_special",
        "listing_type_name": "Clásica",
        "requires_picture": true,
        "sale_fee_amount": 883,
        "sale_fee_details": {
            "financing_add_on_fee": 4,
            "fixed_fee": 0,
            "gross_amount": 883,
            "meli_percentage_fee": 4.83,
            "percentage_fee": 8.83
        },
        "stop_time": "2043-09-14T00:00:00.000-04:00"
    }
]

That is, in the "Notebooks" domain with the mshops_pcj-co-funded tag, the selling fee in Mercado Shops will be 4.83% and the fee for offering payments in three to twelve installments will be 4%, total fee of 8.83%.



Listings in campaign

To check if a product has enabled some of the possible campaigns from three to twelve installments with low interest rate, three installments at the same price you listed and some of the options of "Cuota Simple 3" and "Cuota Simple 3" programs,perform a GET to the "/items" feature with its "item_id" and check if it has the mshops_pcj-co-funded, mshops_3x_campaign, mshops_cuota-simple-3 or mshops_cuota-simple-6 inside the tags.


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1234123456

Response:


{
    "id": "MLA1234123456",
    "site_id": "MLA",
    "title": "Procesador De Alimentos",
    "subtitle": null,
    "seller_id": 553421365,
    "category_id": "MLA3530",
    "official_store_id": null,
    "price": 34345345,
    "base_price": 34345345,
    "original_price": null,
    "currency_id": "ARS",
    "initial_quantity": 1000,
    "available_quantity": 500,
    "sold_quantity": 150,
    "sale_terms": [
        {
            "id": "WARRANTY_TYPE",
            "name": "Tipo de garantía",
            "value_id": "6150835",
            "value_name": "Sin garantía",
            "value_struct": null,
            "values": [
                {
                    "id": "6150835",
                    "name": "Sin garantía",
                    "struct": null
                }
            ]
        }
    ],
    "buying_mode": "buy_it_now",
    "listing_type_id": "gold_pro",
    "start_time": "2022-05-16T16:54:20.000Z",
    "stop_time": "2042-05-11T04:00:00.000Z",
    "condition": "new",
    "permalink": "https://articulo.mercadolibre.com.ar/MLA-1137574968-procesador-de-alimentos-_JM",
    "thumbnail_id": "979379-MLA45885016540_052021",
    "thumbnail": "http://http2.mlstatic.com/D_979379-MLA45885016540_052021-I.jpg",
    "secure_thumbnail": "https://http2.mlstatic.com/D_979379-MLA45885016540_052021-I.jpg",
    "pictures": [
        {
            "id": "979379-MLA45885016540_052021",
            "url": "http://http2.mlstatic.com/D_979379-MLA45885016540_052021-O.jpg",
            "secure_url": "https://http2.mlstatic.com/D_979379-MLA45885016540_052021-O.jpg",
            "size": "385x500",
            "max_size": "459x596",
            "quality": ""
        }
    ],
    "video_id": null,
    "descriptions": [],
    "accepts_mercadopago": true,
    "non_mercado_pago_payment_methods": [],
    "shipping": {
        "mode": "not_specified",
        "methods": [],
        "tags": [],
        "dimensions": null,
        "local_pick_up": false,
        "free_shipping": false,
        "logistic_type": "not_specified",
        "store_pick_up": false
    },
    "international_delivery_mode": "none",
    "seller_address": {
        "city": {
            "name": "CABA"
        },
        "state": {
            "id": "AR-C",
            "name": "Capital Federal"
        },
        "country": {
            "id": "AR",
            "name": "Argentina"
        },
        "search_location": {
            "state": {
                "id": "TUxBUENBUGw3M2E1",
                "name": "Capital Federal"
            }
        },
        "id": 1098928639
    },
    "seller_contact": null,
    "location": {},
    "coverage_areas": [],
    "attributes": [
        {
            "id": "BRAND",
            "name": "Marca",
            "value_id": "276243",
            "value_name": "Genérica",
            "value_struct": null,
            "values": [
                {
                    "id": "276243",
                    "name": "Genérica",
                    "struct": null
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Otros"
        },
        {
            "id": "ITEM_CONDITION",
            "name": "Condición del ítem",
            "value_id": "2230284",
            "value_name": "Nuevo",
            "value_struct": null,
            "values": [
                {
                    "id": "2230284",
                    "name": "Nuevo",
                    "struct": null
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Otros"
        }
    ],
    "warnings": [],
    "listing_source": "",
    "variations": [],
    "status": "active",
    "sub_status": [],
    "tags": [
        "good_quality_picture",
        "standard_price_by_channel",
        "test_item",
        "immediate_payment",
        "mshops_cuota-simple-6"
    ],
    "warranty": "Sin garantía",
    "catalog_product_id": null,
    "domain_id": "MLA-UNCLASSIFIED_PRODUCTS",
    "parent_item_id": null,
    "differential_pricing": null,
    "deal_ids": [],
    "automatic_relist": false,
    "date_created": "2022-05-16T16:54:20.000Z",
    "last_updated": "2022-07-12T15:17:19.561Z",
    "health": 0.8,
    "catalog_listing": false,
    "channels": [
        "marketplace",
        "mshops"
    ]

Creating a listing in a campaign

To create an item within a campaign, you must perform a POST to the "/items" feature including the tag corresponding to the campaign you want to add: mshops_pcj-co-funded, mshops_3x_campaign, mshops_cuota-simple-3 or mshops_cuota-simple-6. Remember to always submit the buying_mode, attribute, as it is required in the POST to create an item.


The items eligible to offer up to six installments with the participation in the Cuota Simple program must be new products and their listing must be Premium, that is, only those with listing_type_id: gold_pro.


Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items
{
    "title": "Item de testeo por favor no ofertar kc:off",
    "pictures": [
        ..
    ],
    "price": 53936,
    "variations": [],
    "shipping": {
        ..
    },
    "currency_id": "ARS",
    "location": {},
    "attributes": [
        ...
    ],
    "listing_type_id": "gold_pro",
    "available_quantity": 543,
    "category_id": "MLA1611",
    "condition": "new",
    "buying_mode": "buy_it_now",
    "tags": [
        "mshops_cuota-simple-6"       
    ]
     ...
}

Response:

{
   "id": "MLA810693730",
   "site_id": "MLA",
   "title": "Item De Test - No Ofertar",
   "subtitle": null,
   "seller_id": 443024908,
   "category_id": "MLA3530",
   "official_store_id": null,
   "price": 100,
   "base_price": 100,
   "original_price": null,
   "inventory_id": null,
   "currency_id": "ARS",
   "initial_quantity": 1,
   "available_quantity": 1,
   "sold_quantity": 0,
   "sale_terms": [],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_pro",
   "start_time": "2019-08-22T17:33:51.000Z",
   "stop_time": "2039-08-17T04:00:00.000Z",
   "end_time": "2039-08-17T04:00:00.000Z",
   "expiration_time": "2019-11-10T17:33:51.000Z",
   "condition": "new",
   "descriptions": [],
   "accepts_mercadopago": true,
   "non_mercado_pago_payment_methods": [],
   "international_delivery_mode": "none",
   "seller_contact": null,
   "location": {},
   "geolocation": {
       "latitude": -34.5780655,
       "longitude": -58.4265317
   },
   "coverage_areas": [],
   "warnings": [],
   "listing_source": "",
   "variations": [],
   "status": "active",
   "sub_status": [],
   "tags": [
       "mshops_cuota-simple-6",
        "immediate_payment",
        "test_item"
   ],
   "warranty": null,
   "catalog_product_id": null,
   "domain_id": "MLA-UNCLASSIFIED_PRODUCTS",
   "seller_custom_field": null,
   "parent_item_id": null,
   "differential_pricing": null,
   "deal_ids": [],
   "automatic_relist": false,
   "date_created": "2019-08-22T17:33:51.000Z",
   "last_updated": "2019-08-22T18:37:41.468Z",
   "health": null,
   "catalog_listing": false,
   "item_relations": []
}

Please remember that we will return an HTTP 400 error whenever you don't meet the requirements or in cases in which:

  • The seller is not enabled to participate in the campaign.
  • The item is used or reconditioned.
  • The exposition of the listing is not "Premium".


Enabling a campaign

To enable the campaign on an item, you must perform a PUT to the "/items" feature including the corresponding mshops_pcj-co-funded, mshops_3x_campaign , mshops_cuota-simple-3 or mshops_cuota-simple-6 tags. Please note that if the item has other tags, they must also be submitted in the edition.


The items enabled to offer up to six installments with the participation in the Cuota Simple dprogram must be new products and their listing must be Premium, that is, only those with listing_type_id: gold_pro.


Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
   "tags":[
      "mshops_cuota-simple-6",
      "immediate_payment",
      "test_item"
   ]
}
https://api.mercadolibre.com/items/$ITEM_ID

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
   "tags":[
      "mshops_cuota-simple-6"
   ]
}
https://api.mercadolibre.com/items/MLA810693730

Response:

{
   "id": "MLA810693730",
   "site_id": "MLA",
   "title": "Item De Test - No Ofertar",
   "subtitle": null,
   "seller_id": 443024908,
   "category_id": "MLA3530",
   "official_store_id": null,
   "price": 100,
   "base_price": 100,
   "original_price": null,
   "inventory_id": null,
   "currency_id": "ARS",
   "initial_quantity": 1,
   "available_quantity": 1,
   "sold_quantity": 0,
   "sale_terms": [],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_pro",
   "start_time": "2019-08-22T17:33:51.000Z",
   "stop_time": "2039-08-17T04:00:00.000Z",
   "end_time": "2039-08-17T04:00:00.000Z",
   "expiration_time": "2019-11-10T17:33:51.000Z",
   "condition": "new",
   "descriptions": [],
   "accepts_mercadopago": true,
   "non_mercado_pago_payment_methods": [],
   "international_delivery_mode": "none",
   "seller_contact": null,
   "location": {},
   "geolocation": {
       "latitude": -34.5780655,
       "longitude": -58.4265317
   },
   "coverage_areas": [],
   "warnings": [],
   "listing_source": "",
   "variations": [],
   "status": "active",
   "sub_status": [],
   "tags": [
       "mshops_cuota-simple-6",
       "immediate_payment",
       "test_item"
   ],
   "warranty": null,
   "catalog_product_id": null,
   "domain_id": "MLA-UNCLASSIFIED_PRODUCTS",
   "seller_custom_field": null,
   "parent_item_id": null,
   "differential_pricing": null,
   "deal_ids": [],
   "automatic_relist": false,
   "date_created": "2019-08-22T17:33:51.000Z",
   "last_updated": "2019-08-22T18:37:41.468Z",
   "health": null,
   "catalog_listing": false,
   "item_relations": []
}

Please remember that we will return an HTTP 400 error whenever you don't meet the requirements or in cases in which:

  • The seller is not enabled to participate in the campaign.
  • The item is used or reconditioned.
  • The exposition of the listing is not "Premium".


Disabling a campaign

To disable the campaign on an item, you must perform a PUT to the "/items" feature including all the tags it had previously, except the tag that refers to campaigns such as mshops_pcj-co-funded, mshops_3x_campaign, mshops_cuota-simple-3 or mshops_cuota-simple-6as applicable:


Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "tags": [
       "immediate_payment",
       "test_item"
   ],
}
https://api.mercadolibre.com/items/$ITEM_ID

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "tags": [
       "immediate_payment",
       "test_item"
   ],
}
https://api.mercadolibre.com/items/MLA810693730

Response:

{
   "id": "MLA810693730",
   "site_id": "MLA",
   "title": "Item De Test - No Ofertar",
   "subtitle": null,
   "seller_id": 443024908,
   "category_id": "MLA3530",
   "official_store_id": null,
   "price": 100,
   "base_price": 100,
   "original_price": null,
   "inventory_id": null,
   "currency_id": "ARS",
   "initial_quantity": 1,
   "available_quantity": 1,
   "sold_quantity": 0,
   "sale_terms": [],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_pro",
   "start_time": "2019-08-22T17:33:51.000Z",
   "stop_time": "2039-08-17T04:00:00.000Z",
   "end_time": "2039-08-17T04:00:00.000Z",
   "expiration_time": "2019-11-10T17:33:51.000Z",
   "condition": "new",
   "descriptions": [],
   "accepts_mercadopago": true,
   "non_mercado_pago_payment_methods": [],
   "international_delivery_mode": "none",
   "seller_contact": null,
   "location": {},
   "geolocation": {
       "latitude": -34.5780655,
       "longitude": -58.4265317
   },
   "coverage_areas": [],
   "warnings": [],
   "listing_source": "",
   "variations": [],
   "status": "active",
   "sub_status": [],
   "tags": [
       "immediate_payment",
       "test_item"
   ],
   "warranty": null,
   "catalog_product_id": null,
   "domain_id": "MLA-UNCLASSIFIED_PRODUCTS",
   "seller_custom_field": null,
   "parent_item_id": null,
   "differential_pricing": null,
   "deal_ids": [],
   "automatic_relist": false,
   "date_created": "2019-08-22T17:33:51.000Z",
   "last_updated": "2019-08-22T18:37:41.468Z",
   "health": null,
   "catalog_listing": false,
   "item_relations": []
}