Campaigns with installments for Marketplace

Listings in which you choose not to add installments

The gold_special listings, only have the installments with interest rates that the banks offer. For that reason, you only pay the selling fee and, if applicable, the per unit fee.

• Installments with interest rates - Programa Cuota Simple (cuota-simple PBB): with this option, buyers will have better financing (they will pay the program's financing rates). To do so, please modify your listings and enable them with the cuota-simple-paid-by-buyer tag.
• Installments with low interest rates: with this option you pay 4% to offer your buyers from 3 to 12 installments with a lower interest rate than the banks. This way you will be able to offer more competitive prices. To do so, modify your listings and enable them with the pcj-co-funded. Check Terms and Conditions.

If you have a Mercado Shops store, we invite you to access the documentation for more details. //LINK

Listings in which you choose to add installments

In the publicaciones gold_pro, by offering more convenient installments to buyers, you pay the selling fee plus a fee for offering installments, and the per unit fee if applicable.

• 3 installments for the same price you listed: you will have a percentage discount on the selling fee. This way you will be able to offer more competitive prices. To do so, modify your listings and enable them with the 3x_campaign tag. This discount is available for selected categories.
// LINK
• 6 installments for the same price you listed: you will have a percentage discount on the selling fee. These listings (6x) do not have an associated tag in /items. When you register a listing in gold_pro, you will offer the 6 installments by default at the same price you list. View fees for adding installments.
• Cuota Simple Program: in listings eligible to participate in the program, you will have a % discount on the selling fee depending on the number of installments you choose. This way you will be able to offer more competitive prices. To do so, modify your listings and and activate the option of installments at the same price you publish with the tags cuota-simple-3, cuota-simple-6 or cuota-simple-paid-by-buyer tags as appropriate. This discount will be available for selected categories Terms and Conditions .

If you have a Mercado Shops store, we invite you to access the documentation for more details. //LINK

Comparison between installment options

Listings in which you choose not to add installments

Listings in which you choose to add installments

Find out if the user is enabled to join the campaign

To find out which user has the possibility to join existing campaigns, you must perform a GET to the /special_installments resource, as appropriate, with the $SELLER_ID.

Optional parameters:

• cuota-simple-paid-by-buyer: Cuota Simple Program in gold_special.
• pcj-co-funded: 3 to 12 installments with low interest rates campaign.
• 3x_campaign: 3 installments for the same price you listed.
• cuota-simple-3: Cuota Simple Program 3 in gold_pro.
• cuota-simple-6: Cuota Simple Program 6 in gold_pro

In the event that the user is able to participate, the date on which they were enabled will be displayed.

Request:

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

Example:

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

Response:

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

If the user is NOT allowed to offer the queried campaign, the response will be:

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

Find out which categories can be added to the campaign

You must perform a POST to the resource /special_installments according to the corresponding campaign, with the $CATEGORY_ID (e.g.: pcj-co-funded, 3x_campaign)

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/special_installments/$CAMPAIGN_TAG_ID/categories/$CATEGORY_ID/enabled

Response Body: will give as the response the field "enabled" with the value true or false, as appropriate.
Response Status: 200
Cacheable: Yes, the "Cache-Control" header will be given with the value "max-age=$max-age" indicating the recommended time in seconds to cache the information that the resource responds to.

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/special_installments/3x_campaign/categories/MLA1055/enabled

Response:

{
   "enabled": true
}

Remember that, for the Cuota Simple Program, the products must be manufactured in Argentina and in the body a JSON with the brand ($brand) and model ($model) as appropriate.

Optional parameters:

• cuota-simple-paid-by-buyer: Cuota Simple Program in gold_special.
• cuota-simple-3: Cuota Simple Program 3 in gold_pro.
• cuota-simple-6: Cuota Simple Program 6 en gold_pro.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/special_installments/$CAMPAIGN_TAG_ID/categories/$CATEGORY_ID/enabled

Response Body: will give as the response the field "enabled" with the value true or false, as appropriate.

Response status: 200

Cacheable: Yes, the "Cache-Control" header will be given with the value "max-age=$max-age" indicating the recommended time in seconds to cache the information that the resource responds to.

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/special_installments/cuota-simple-6/categories/MLA1055/enabled
{
   "brand":"Motorola",
   "model":"Z1",
   "alphanumeric_model":"Z1 - 312 fD4"
}

Response:

{
   "enabled":true
}

This case indicates that a Motorola branded item, model Z1 and alphanumeric model "Z1-312fD4" is participating in the program.

Find out if a listing is in the campaign

To check if a listing in which you choose not to add installments (gold_special) has any campaign enabled, perform a GET to the /items resource with its item_id and verify that it has the cuota-simple-paid-by-buyer or pcj-co-funded tag in the fields.

To check if a listing in which you choose to add installments (gold_pro) has any campaign enabled, perform a GET to the /items resource with its item_id and verify that it has the 3x_campaign, cuota-simple-3 or cuota-simple-6 tags in the fields. Remember that gold_pro listings with “6 installments for the same price you listed” (6x) do not have a tag linked in /items.

Request:

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

Example:

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

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": [
       "3x_campaign",
       "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": []
}

View selling fees by filtering campaigns

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

Remember:

1. Respect the relation listing_type+tag (ver opciones) . //LINK al nuevo "Comparison between installment options"
2. Filter by channel to view specific commissions. Otherwise, you will view the ones from the marketplace by default.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE/listing_prices?price=$PRICE&listing_type_id=$LISTING_TYPE_ID&tags=$CAMPAIGN_TAG_ID&domain_id=$DOMAIN_ID

Example from 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:

[
    {
        "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": 2700,
        "sale_fee_details": {
            "financing_add_on_fee": 15,
            "fixed_fee": 0,
            "gross_amount": 2700,
            "meli_percentage_fee": 12,
            "percentage_fee": 27
        },
        "stop_time": "2043-09-09T00:00:00.000-04:00"
    }
]
}
]

That is, in the Notebooks domain with the 3x_campaign, tag, the selling fee on Marketplace will be 12% and the fee for offering installments will be 15%, total fees of 27%. For more information, you can consult resources to obtain the selling fees and the meaning of each field in the answer.

Example from the Cell phones domain:

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

Response:

[
    {
        "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": 1600,
        "sale_fee_details": {
            "financing_add_on_fee": 4,
            "fixed_fee": 0,
            "gross_amount": 1600,
            "meli_percentage_fee": 12,
            "percentage_fee": 16
        },
        "stop_time": "2043-09-09T00:00:00.000-04:00"
    }
]

That is, in the Cell phones domain with thepcj-co-funded, tag, the selling fee in Marketplace will be 12% and the fee for offering installments will be 4%, total fees of 16%. For more information you can consult resources to obtain the selling fees. .

Create a listing in a campaign

You must perform the POST to the /items resource including the corresponding tag (view options). Please note to always send the buying_mode attribute as it is required in the POST and the products must be new.
In addition, remember that the listings with the Cuota Simple Program must be within the categories, brands and models enabled that confirm that it is a national product. Recognize which products can be added to the campaign .

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": [
        "3x_campaign"       
    ]
     ...
}

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": [
       "3x_campaign",
       "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": []
}

Remember that we will generate an "http error 400" whenever you do not meet the requirements or in cases that:

• The category is not enabled to offer installments.
• The seller is not qualified to participate in the Cuota Simple Program.
• The product is used or reconditioned.
• The listing_type of the listing does not match the campaign tag sent (ver opciones).
• The brand or model of the product does not participate in the campaign (in listings with Cuota Simple).

Enable the campaign in a listing

You must perform a PUT to the /items resource including the corresponding tag (view optionns). Note that if the item_id contains other tags, they must also be sent in the modification.

In addition, remember that they must be new products and the listings in the Cuota Simple Program must be within the categories, brands and models enabled that confirm that it is a national product. Recognize which products can be added to the campaign.

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "tags": [
       "3x_campaign",
       "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": [
       "3x_campaign",
       "immediate_payment",
       "test_item"
   ]
}
https://api.mercadolibre.com/items/MLA810693730

Answer:

{
   "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": [
       "3x_campaign", 
       "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": []
}

Remember that we will return an "http error 400" whenever you do not meet the requirements or in cases that:

• The category is not qualified to offer installments.
• The seller is not qualified to participate in the Cuota Simple program.
• The product is used or reconditioned.
• The listing_type of the listing does not match the campaign tag sent (view options).
• The brand or model of the product does not participate in the campaign (in listings with Cuota Simple).

Disable the campaign in a listing

To disable the campaign on an item_id, you must perform a PUT to the /items resource including all the tags it had previously except the tag you want to remove (cuota-simple-paid-by-buyer, pcj-co-funded, 3x_campaign, cuota-simple-3 o cuota-simple-6).

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": []
}