Manage Package (Real Estate)

Package Types

There are 2 types of packages:

• Listing package: mandatory for seller to make publications. This is the Silver package, that is, listing_type = silver.
• Upgrade package: this is an optional package; the seller uses it to increase publication exposure. This can be Other (listing_type = gold) or Other Premium (listing_type = gold_premium).

These two packages offer quotas to be used per each posted publication (in case of a listing package) and every time an update / upgrade occurs (in case of upgrade package). Today, each user needs to engage a listing and upgrade package via a Mercado Libre account representative. This action cannot be done via API.
The listing_type used to post a publication will always be: "Silver", and in the event of upgrading a publication, the listing will need to be updated with the intended listing_type (and one upgrade package quota is used).

Remember that in GET requests to API resource classifieds_promotion_packs, you can use package_content parameter (package type) to learn about what package to query:

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/MLA1743/classifieds_promotion_packs

Response:

[
  {
    "id": "MPAB",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 15 Básico",
    "price": 819.17,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCAA",
    "max_upgrades": 0,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 15
      }
    ]
  },
  {
    "id": "MPAE",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 15 Especial",
    "price": 1157.97,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCAS",
    "max_upgrades": 0,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 5
      },
      {
        "listing_type_id": "silver",
        "available_listings": 10
      }
    ]
  },
  {
    "id": "MPAP",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 15 Premium",
    "price": 1629.87,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCAR",
    "max_upgrades": 0,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 8
      },
      {
        "listing_type_id": "gold",
        "available_listings": 6
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 1
      }
    ]
  },
  {
    "id": "MPBB",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 30 Básico",
    "price": 1242.67,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCBA",
    "max_upgrades": 0,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 30
      }
    ]
  },
  {
    "id": "MPBE",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 30 Especial",
    "price": 1617.77,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCBS",
    "max_upgrades": 0,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 10
      },
      {
        "listing_type_id": "silver",
        "available_listings": 20
      }
    ]
  },
  {
    "id": "MPBP",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 30 Premium",
    "price": 2246.97,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCBR",
    "max_upgrades": 0,
    "quota_type": "reusable",
    "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": "MPCB",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 300 Básico",
    "price": 2839.87,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCEA",
    "max_upgrades": 0,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 300
      }
    ]
  },
  {
    "id": "MPCE2",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 300 Especial",
    "price": 5526.07,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCES",
    "max_upgrades": 300,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 90
      },
      {
        "listing_type_id": "silver",
        "available_listings": 210
      }
    ]
  },
  {
    "id": "MPCP2",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 300 Premium",
    "price": 11200.97,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCER",
    "max_upgrades": 300,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 180
      },
      {
        "listing_type_id": "gold",
        "available_listings": 95
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 25
      }
    ]
  },
  {
    "id": "MPDB",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 60 Básico",
    "price": 1424.17,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCCA",
    "max_upgrades": 0,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 60
      }
    ]
  },
  {
    "id": "MPDE",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 60 Especial",
    "price": 2162.27,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCCS",
    "max_upgrades": 0,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 20
      },
      {
        "listing_type_id": "silver",
        "available_listings": 40
      }
    ]
  },
  {
    "id": "MPDP",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 60 Premium",
    "price": 3529.57,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCCR",
    "max_upgrades": 0,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 32
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 4
      },
      {
        "listing_type_id": "gold",
        "available_listings": 24
      }
    ]
  },
  {
    "id": "MPEB",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 100 Básico",
    "price": 2029.17,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCDA",
    "max_upgrades": 0,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 100
      }
    ]
  },
  {
    "id": "MPEE2",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 100 Especial",
    "price": 3118.17,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCDS",
    "max_upgrades": 300,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 30
      },
      {
        "listing_type_id": "silver",
        "available_listings": 70
      }
    ]
  },
  {
    "id": "MPEP2",
    "category_id": "MLA1743",
    "brand": "MLMOTORS",
    "description": "Paquete 100 Premium",
    "price": 5271.97,
    "package_type": "rotary",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCDR",
    "max_upgrades": 300,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 30
      },
      {
        "listing_type_id": "silver",
        "available_listings": 60
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 10
      }
    ]
  }
]

Query packages by category

To query available packages for classified categories, first you need to know the category to be used and site. For example, in Brazil real estate category is MLB1459.

Example:

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

Response:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/MLB1459/classifieds_promotion_packs
[
  {
    "id": "PUS30FREE",
    "category_id": "MLB1459",
    "brand": "MLREALESTATE",
    "description": "All your stock",
    "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 is an important query whereby you can know the packages a client has and the number of listings available in each of them by entering user ID (client), package content and token.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/classifieds_promotion_packs/$LISTING_TYPE?categoryId=$CATEGORY_ID

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
        }
     ]
    }
]

Pay attention to field status = active, whereby you can only check the still active plans. With package_content, you can check if it is a publications or upgrades package. Finally, remaining_listings field shows the number of publications still available for the client. In your system, you will see the number of packages a client has and the number of publications to list and upgrade before sending a posting to Mercado Libre.

Resource description

Check if a user has a specific listing_type available

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

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/users/$USER_ID/classifieds_promotion_packs/$LISTING_TYPE?categoryId=$CATEGORY_ID

Upgrade an Advertisement (highlight)

To highlight an ad, you must perform the following post; remember that in order to be able to perform this action, the user must have previously contracted a highlight 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":"listing_type"}

In the example above, the ad is upgrading to listing type = gold_premium (diamond). Remember also that no charges are generated when making this call, and that if the upgrade is undone, the highlight quota becomes available again.
It is also not possible to highlight a publication without hiring at least one highlight package.

Validity time of the publication

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:

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




For houses and apartments for sale, API will finalize the item after 180 days of publication.

• Apartment for sale - Category ID: MLC157522
• House for sale - Category ID: MLC157520



For house and apartment rentals, API will close the item after 45 days of publication (only applies to rentals, does not apply to temporary rentals).

• Apartment for rent - Category ID: MLC183186
• House for rent - Category ID: MLC183184



These last 2 life cycle conditions apply only to MLC.




Meaning of the item life cycle time parameters for apartments and houses:

start_time: the API defines it when creating the item.

stop_time: the API sets it at item creation time according to the category (either sale or lease).

expiration_time: the API sets when creating the item according to the duration of the promotional package (active publishing package you have)




When the item reaches Stop_time, the API terminates the item; the status of the item changes from active to closed substatus expired.
When the package is active and the item is dropped 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.




Ejemple:

An item Apartment for Sale (Category MLC157522) that was posted with:

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

stop_time: "2022-06-01T00:06:15.000Z",

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




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.


Next: List properties