Despegue program and Reputation Benefit

Notifications

Currently, sellers are notified via email, notifications, and news on Mercado Libre. Use the news API (/communications/notices) to inform sellers about their invitation as soon as they are invited. A new notification topic will be enabled soon.

Check reputation

First, check the seller's reputation to ensure eligibility for a program. If the seller has no color reputation, red, orange, or yellow reputation levels, use the following endpoints. Sellers with green reputation levels (id: 4_light_green or 5_green) are excluded.

Request:

curl -X GET -H 'Authorization: Bearer Token' https://api.mercadolibre.com/users/$USER_ID

Response:

{
  "id": 123456,
  ...
  "seller_reputation": {
    "level_id": null,
    "power_seller_status": null,
    "transactions": {
      ...
    },
    "total": 8
  }
  ...
}

Get program details

The seller eligible to participate in a program can obtain detailed information about protection, guarantees, limits, and available funds in Mercado Ads.

Request:

curl -X GET -H 'Authorization: Bearer Token' https://api.mercadolibre.com/users/reputation/seller_recovery/status

Response:

{
    "seller_id": 453616456,
    "current_level": "newbie",
    "status": "AVAILABLE",
    "type": "NEWBIE_GRNTEE",
    "site_id": "MLA",
    "protection_limits": {
        "max_issues_allowed": 5,
        "protection_days_limit": 365
    },
    "guarantee_limits": {
        "guarantee_price": "$45.000",
        "advertising_amount": 45000
    },
    "guarantee_detail": {
        "guarantee_status": "OFF"
    },
    "is_renewal": false
}

Response fields

seller_id: seller ID.

status: current protection status. Possible values:

• AVAILABLE: protection enabled.
• ACTIVE: protection activated.
• UNAVAILABLE: protection not available.
• FINISHED_BY_DATE: protection ended due to date.
• FINISHED_BY_ISSUES: protection ended due to issues.
• FINISHED_BY_LEVEL: protection ended due to recovered value..
• FINISHED_BY_USER: protection canceled by the seller.
• FINISHED: protection ended for various reasons.

type: protection type: Programa de Despegue (NEWBIE_GRNTEE) or Programa Seller Recovery (RECOVERY_GRNTEE).
site_id: site.

protection_limits: protection limits.

• max_issues_allowed: maximum number of allowed issues.
• protection_days_limit: duration (days) of protection.

guarantee_limits: warranty limits.

• guarantee_price: value of the warranty.
• advertising_amount: value of the bonus in Mercado Ads. Applies only to Despegue program (NEWBIE_GRNTEE).

protection_detail: details about the current protection.

• warning: alert regarding the expiration of protection.
• reactivated: indicate if the protection was reactivated.
• init_date: start date of the protection.
• end_date: end date of the protection.
• protection_days: days of active protection.
• start_level: seller color when starting the protection.
• end_level: seller color when ending the protection.

sales_detail: sales details during the protection.

• orders_qty: quantity of orders sold.
• total_issues: seller issues.
• claims_qty: number of claims.
• cancel_qty: number of cancellations.
• delay_qty: number of delayed shipments.

guarantee_detail: details about the warranty.

• guarantee_status: warranty status.
• guarantee_end_date: warranty end date.
• guarantee_buffer: duration of the buffer to evaluate the warranty.
• guarantee_release_amount: warranty reserve money.
• guarantee_charge_amount: warranty charge money.

Activate Program

Before activating the program, the seller must deposit the previously reported amount of money into their Mercado Pago account or reserve said amount if they already have money in their account. If they do not have the money available, they will receive an error when activating the program. Once the seller activates the program (opt-in), the protection period begins.

Request:

curl -X POST -H 'Authorization: Bearer Token' -H 'Content-Type: application/json' https://api.mercadolibre.com/users/reputation/seller_recovery/activate

Response:

{
  "message": "ok"
}

Deactivate program

At any time, the seller may request cancellation and submit the following mandatory parameter: cancellation_reason: reason for the cancellation of the program (mandatory for the Startup Program, not required for Recovery Color). Possible values:

• business_not_ready: my business is not ready.
• program_not_useful: the program was not useful to me.
• need_money: I need the money.
• goal_achieved: I have already achieved my goal.
• without_reason: no reason.

Example:

curl -X PUT -H 'Authorization: Bearer Token' -H 'Content-Type: application/json'-D 
{
    "cancellation_reason" : "goal_achieved"
}
https://api.mercadolibre.com/users/reputation/seller_recovery/cancel_guarantee

Response:

{
   "message": "ok"
}

Download Legal Authorization

Those integrators with users (sellers) from Mexico and Colombia are legally required to show the sellers from these countries the download of the legal authorization, which may be a preliminary and complete version.

Mandatory parameter

type: this is the type of legal authorization that you can download. Possible values:

• preview: it is only possible to call in preview mode if the protection is in AVAILABLE status and the warranty is in OFF status.
• complete: once the seller has activated the program's protection (either Acceleration or Recovery), they can download the complete document. It can only be downloaded if the protection is in ACTIVE or FINISHED_BY_* status.

Request:

curl -X GET -H 'Authorization: Bearer Token' https://api.mercadolibre.com/users/reputation/seller_recovery/legal-document?type=(PREVIEW|COMPLETE)

Response:

{
    "document": "JVBERi0xLjQKJfbk/N8KMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovVmVyc2lvbiAvMS41Ci9QYWdlcyAyIDAgUgovTmFtZXMgMyAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL01vZERhdGUgKEQ6MjAyNDA5MTkxN"
}

For security reasons, the response will be a base64-encoded data type, which you can decode using a python script and obtain the pdf.
Example:

import base64

# The base64 string you provided
base64_data = ""  

# Add the proper padding if necessary
base64_data = base64_data.rstrip('=')  # Remove any previous padding, if there is any
padding_needed = len(base64_data) % 4
if padding_needed:
    base64_data += '=' * (4 - padding_needed)

# Decode the base64 string
pdf_data = base64.b64decode(base64_data)

# Save the binary data as a PDF file
with open('output.pdf', 'wb') as pdf_file:
    pdf_file.write(pdf_data)

print("PDF saved as output.pdf")

To activate these programs on test users, send us 2 test users with null reputation (no color) via Support and we will activate a program on each of them.

Next: Seller reputation.