Manage packages

Promotions Packs are listing packages for Car Dealers and Real State Agency Classifieds listings. In this tutorial you’ll learn how to get information about packages and also engage and activate a package.

Contents:

Obtain packages by category

The possible values for classifieds_promotion_packs categories are different each site. Possible values are:
{site_id}1743: Car Dealer.
{site_id}1459: Real Estate Agency.
For example, on Argentina, Car Dealer package category it’s MLA1743 while in Brazil it’s MLB1743
Make a GET to look for packages in an specific category:

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

Response:

[
  {
    "id": "IPAA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 15 Básico",
    "price": 350,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCAA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 15
      }
    ]
  },
  {
    "id": "IPAR",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 15 Premium",
    "price": 600,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCAR",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 6
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 1
      },
      {
        "listing_type_id": "silver",
        "available_listings": 8
      }
    ]
  },
  {
    "id": "IPAS",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 15 Especial",
    "price": 410,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCAS",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 10
      },
      {
        "listing_type_id": "gold",
        "available_listings": 5
      }
    ]
  },
  {
    "id": "IPBA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 30 Básico",
    "price": 480,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCBA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 30
      }
    ]
  },
  {
    "id": "IPBR",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 30 Premium",
    "price": 880,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCBR",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 16
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 2
      },
      {
        "listing_type_id": "gold",
        "available_listings": 12
      }
    ]
  },
  {
    "id": "IPBS",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 30 Especial",
    "price": 560,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCBS",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 20
      },
      {
        "listing_type_id": "gold",
        "available_listings": 10
      }
    ]
  },
  {
    "id": "IPCA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 60 Básico",
    "price": 570,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCCA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 60
      }
    ]
  },
  {
    "id": "IPCR",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 60 Premium",
    "price": 910,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCCR",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 32
      },
      {
        "listing_type_id": "gold",
        "available_listings": 24
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 4
      }
    ]
  },
  {
    "id": "IPCS",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 60 Especial",
    "price": 650,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCCS",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 20
      },
      {
        "listing_type_id": "silver",
        "available_listings": 40
      }
    ]
  },
  {
    "id": "IPDA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 100 Básico",
    "price": 750,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCDA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 100
      }
    ]
  },
  {
    "id": "IPDR",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 100 Premium",
    "price": 1180,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCDR",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold_premium",
        "available_listings": 5
      },
      {
        "listing_type_id": "gold",
        "available_listings": 35
      },
      {
        "listing_type_id": "silver",
        "available_listings": 60
      }
    ]
  },
  {
    "id": "IPDS",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 100 Especial",
    "price": 820,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCDS",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 25
      },
      {
        "listing_type_id": "silver",
        "available_listings": 75
      }
    ]
  },
  {
    "id": "IPEA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 500 Básico",
    "price": 850,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCEA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 500
      }
    ]
  },
  {
    "id": "IPER",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 500 Premium",
    "price": 1900,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCER",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 100
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 15
      },
      {
        "listing_type_id": "silver",
        "available_listings": 385
      }
    ]
  },
  {
    "id": "IPES",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 500 Especial",
    "price": 1000,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCES",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 70
      },
      {
        "listing_type_id": "silver",
        "available_listings": 430
      }
    ]
  }
]

Get packages engaged by an user

curl -X GET https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs?access_token=$ACCESS_TOKEN;

Response:

[
	{
    	"id": 754985,
    	"user_id": "135146148",
    	"promotion_pack_id": "MPAB",
    	"category_id": "MLU1743",
    	"description": "Paquete 15 Básico",
    	"package_type": "rotary",
    	"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
        	}
    	]
	}
]

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.

Check if an user has an specific listing_type available

curl -X GET https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs/{listing_type}ilver& categoryId={Category_id}?access_token=$ACCESS_TOKEN

Response:

{
  "has_available_listings": true
}

Engage and activate a package

You can engage a package and activate it by making a POST to the API like in the following example:

curl -X POST "Content-type:application/json" -d '{
"categ_id":"MLA1459", "promotion_pack_id":"IPIN", "engagement_type":"none", "status":"active"
}' https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs&access_token=$ACCESS_TOKEN

The current documentation focusses on the new logic for upgrades packages currently working only for real estate agencies for Argentina, Brazil, Mexico and Uruguay. The new upgrade packages logic consists in migrating the actual model where charges are being generated for individual upgrades, to an analog logic on listings packages where the client hires an upgrade package and then every upgrade done occupies a place or quota in the package.

Upgrade the item

POST https://api.mercadolibre.com/items/{item_id}/listing_type?access_token=$ACCESS_TOKEN
BODY
{ “id”:”{listing_type}” }

The response is the item updated.
Example:

curl -X POST --header "Content-type:application/json" -d '{"id":"gold"}' 'https://api.mercadolibre.com/items/MLA563940625/listing_type?access_token=$ACCESS_TOKEN'
{
    "id": "MLA563940625",
    "site_id": "MLA",
    "title": "Test 10 No Ofertar",
    "subtitle": null,
    "seller_id": 184854440,
    "category_id": "MLA50543",
    "official_store_id": null,
    "price": 2928282,
    "base_price": 2928282,
    "original_price": null,
    "currency_id": "ARS",
    "initial_quantity": 1,
    "available_quantity": 1,
    "sold_quantity": 0,
    "buying_mode": "classified",
    "listing_type_id": "gold",
    "start_time": "2015-06-09T20:25:50.000Z",
    "stop_time": "2015-07-05T19:51:17.587Z",
    "end_time": "2015-07-05T19:51:17.587Z",
    "condition": "not_specified",
    "permalink": "http://inmueble.mercadolibre.com.ar/MLA-563940625-test-10-no-ofertar-_JM",
    "thumbnail": "http://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-I.jpg",
    "secure_thumbnail": "https://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-I.jpg",
    "pictures": [
        {
            "id": "302401-MLA20317818801_062015",
            "url": "http://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-O.jpg",
            "secure_url": "https://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-O.jpg",
            "size": "500x281",
            "max_size": "1200x675",
            "quality": ""
        }
    ],
    "video_id": null,
    "descriptions": [],
    "accepts_mercadopago": false,
    "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": 163310864,
        "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": "",
        "longitude": "",
        "search_location": {
            "neighborhood": {
                "id": "TUxBQlBBTDI1MTVa",
                "name": "Palermo"
            },
            "city": {
                "id": "TUxBQ0NBUGZlZG1sYQ",
                "name": "Capital Federal"
            },
            "state": {
                "id": "TUxBUENBUGw3M2E1",
                "name": "Capital Federal"
            }
        }
    },
    "seller_contact": {
        "contact": "",
        "other_info": "",
        "area_code": "",
        "phone": "",
        "area_code2": "",
        "phone2": "",
        "email": "",
        "webpage": ""
    },
    "location": {
        "address_line": "falsa 123 123",
        "zip_code": "",
        "neighborhood": {
            "id": "TUxBQkVTUDYyODRa",
            "name": "Espartillar"
        },
        "city": {
            "id": "TUxBQ0FETzQ2Nzc",
            "name": "Adolfo Alsina"
        },
        "state": {
            "id": "TUxBUFpPTmFpbnRl",
            "name": "Buenos Aires Interior"
        },
        "country": {
            "id": "AR",
            "name": "Argentina"
        },
        "latitude": -34.6635266,
        "longitude": -58.3654707,
        "open_hours": ""
    },
    "geolocation": {
        "latitude": -34.6635266,
        "longitude": -58.3654707
    },
    "coverage_areas": [],
    "attributes": [
        {
            "id": "MLA1459-HORPREF",
            "name": "Horario de contacto",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-ACCESO",
            "name": "Acceso",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-ANTIG",
            "name": "Antigüedad",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-EXPENCEM",
            "name": "Expensas ($)",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-SEGUR",
            "name": "Seguridad",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA1459-INMUEBLE",
            "name": "Inmueble",
            "value_id": "MLA1459-INMUEBLE-COCHERA",
            "value_name": "Cochera",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA1459-OPERACION",
            "name": "Operación",
            "value_id": "MLA1459-OPERACION-VENTA",
            "value_name": "Venta",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-MTRSTOTAL",
            "name": "Superficie total (m²)",
            "value_id": "",
            "value_name": "24",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-TIPCOB",
            "name": "Tipo de cobertura",
            "value_id": "MLA50541-TIPCOB-CUBIERTA",
            "value_name": "Cubierta",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-TIPOCOCH",
            "name": "Tipo de cochera",
            "value_id": "MLA50541-TIPOCOCH-FIJA",
            "value_name": "Fija",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        }
    ],
    "listing_source": "",
    "variations": [],
    "status": "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": "2015-06-09T20:25:50.000Z",
    "last_updated": "2015-06-10T12:20:32.418Z"
}

End Package

PUT https://api.mercadolibre.com/users/186704185/classifieds_promotion_packs/1047628?access_token=$ACCESS_TOKEN
BODY
{ “status”:”{finished}” }

Example:

curl -X PUT -H "Content-Type: application/json" -d'{
> "status":"finished"
> }' https://api.mercadolibre.com/users/186704185/classifieds_promotion_packs/1047628?access_token=$ACCESS_TOKEN

Please rate this