Merchant Portal Guide - API

Version 1.0.0
Login

Link: https://cbt.mercadolibre.com/secure/login/merchant/

Use the registration

credentials
Merchant Portal Modules

Seller Profile, Reputation, Feedback template, User Management, Notifications

Download Files

Listings, Remove SKUs

Manage Open orders, Manage Closed orders

Manage Pre and Post sales Questions

All informations related to your payments

 My Account - Add/update Bank Account

My account Seller profile Add bank account

 My Account - Create account operator

My account User Management

Most Important Accesses for Account Operators

Nombre ejemplo@empresa.com

Nombre ejemplo@empresa.com
 My Account - Email notifications

My account Notifications

ejemplo@empresa.com

ejemplo@empresa.com

ejemplo@empresa.com

ejemplo@empresa.com
 Account Setup and Authentication (AS&A)

Authentication on Meli CBT platform is based on oauth 2.0 standard. In order to get the API credentials you
need to follow these steps:

1. Account Registration: you can request for a productive account thru our support channel
cbt-support@mercadolibre.com
2. CBT Application Creation
3. Application Authorization (generate auth code)
4. Get Access and Refresh Token

For more information visit our CBT API DOCUMENTATION (10. Account Setup & Authentication)
 AS&A - Account Registration

1. Account Registration: you can request for a productive account thru our support channel
cbt-support@mercadolibre.com.

Productive endpoints:
● Merchant Portal: https://cbt.mercadolibre.com
● API: https://api-cbt.mercadolibre.com
 AS&A - CBT Application Creation

2. CBT Application Creation: use the following URL to create your Meli CBT Application
https://cbt.mercadolibre.com/merchant/applications
 AS&A - Application Authorization 1/2

3. Application Authorization: use the following URL format to authorize your application (complete the
bold fields)
https://cbt.mercadolibre.com/merchant/authorization/?client_id=xxxx&response_type=co
de&redirect_uri=http%3A%2F%2Fwww.redirect.uri

client_id: application client id you got in the “CBT Application Creation” step.
redirect_uri: complete the field keeping the “http%3A%2F%2F” prefix

Example:
https://cbt.mercadolibre.com/merchant/authorization/?client_id=31240215021163756245&response_t
ype=code&redirect_uri=http%3A%2F%2Fwww.cbtredirecturi.com
 AS&A - Application Authorization 2/2

You will be redirected to Login page. Once you have logged in, please click on the "Allow" button (notice
that only "admin" user can authorize the application). After this, you will be redirected to the redirect_uri and
the system will return the "auth code" that you will use to get the access and refresh token.
 AS&A - Get Access Token and Refresh Token

4. Get Access Token and Refresh Token: using the “auth code”, client id and client secret you can get
the access token and refresh token.
Example:
Request Response
[POST] https://api-cbt.mercadolibre.com/oauth/token {
Header: Content-Type:application/json "access_token": "xxxxxxxxxx",
Body (JSON): "expires_in": 172800,
{ "token_type": "bearer",
"client_id": "xxxxx", "scope": "read write offline_access",
"client_secret": "xxxxx", "refresh_token": "xxxxxxxxxx",
"grant_type": "authorization_code", "email": "xxxxxxxxxx@xxxxxxxxxx.com"
"code": "xxxxx" }
}
 AS&A - Renew Access Token and Refresh Token

The access token is valid for 6 hours. After that, you must renew it.
Example:

Request Response
[POST] https://api-cbt.mercadolibre.com/oauth/token
Header: Content-Type:application/json {
Body (JSON): "client_id": "xxxxxxxxx",
{ "client_secret": "xxxxxxxxx",
"client_id": "xxxxx", "grant_type": "refresh_token",
"client_secret": "xxxxx", "refresh_token": "xxxxxxxxx"
"grant_type": "refresh_token", }
"refresh_token": "xxxxx"
}
 Product API

In order to publish items, you must take into account the following topics:

1. Categorization
2. Product Validation
3. Add Product
a. Regular product
b. Product with variations
4. Translation
5. Product Statuses
6. Publish Product (unpublish)
7. Update Product
8. Other considerations
 Product API - Categorization

To categorize your products, you should use the MercadoLibre CBT category structure. You must list
your items using the lowest-level category (leaf level) in the category structure. A leaf-level category is
one that has no children or subcategories.

If variations are available, you will see a message that says, "Variations are available for this
category," and underneath the category tree, you will be able to find the values you can use to define
products.

For example, the category 2748 (Clothes, Shoes, and Bags > Athletic Shoes > For Men > Other
Brands > Casual) accepts variations for primary color, secondary color, size and brand. The only two
required attributes are primary color and size.

To submit the primary color (white), you should include Attribute ID 10001 and Attribute Value 10048
 Product API - Product Validation

You can validate the product data before calling add or update product.
Is strongly recommendable use this endpoint to validate previously the product data to avoid errors
with mandatories fields, fields contents, etc.
Request Response
[POST] HTTP 200 OK, if no error.
https://api-cbt.mercadolibre.com/api/SKUs/validate?a OR HTTP error code with error message like this
ccess_token=xxxxxxxxx {
Header: Content-Type:application/json “error”:[
Body (JSON): {
“id”:1005,
{ “code”:”INVALID_CATEGORY_ID”,
“SKU”: “01428510”, “message”:”A valid leaf level category id is required “
“product_type”: “Women Sunglass”, }
“product_title_english”: “Product title in English”, ]
.... }
}
Product API - Add Product 1/6

Regular product
All items are regular products, less the products with variations.

To add a product you must send the required fields:

● SKU: product sku (Max length 50 characters)
● product_title_english: Product title in English (Max length 150 characters)
● description_english: Product description in English Text, max 4000 characters
● specification_english: Product specification in English. The Specification key and value should be
separated by : and multiple specifications separated by ~. Ex: ORIGINAL BRAND
NAME:Citizen~PRODUCT TYPE:Watch~CONDITION:new. (Max length 2000 characters)
● category_id: Leaf level category id from CBT category tree (Numeric field)
● image_url: Product image, the URLs (~^~ separated) . Max 6 images and total pictures size 10MB,
Picture format can be .jpg, .jpeg, .png or .gif (without animation). Ex. 1 image: “http://image.com/q.jpg” -
3 images: “http://image.com/a.jpg~^~http://image.com/b.jpg~^~http://image.com/c.jpg”
Product API - Add Product 2/6

Regular product
● country_of_origin: Product country of origin. You must indicate your country using 2 digit iso country
code (Accepted: US,CN,HK,GB).
● shipping_from: Shipping from country. You must indicate your country using 2 digit iso country code.
● sale_price: Product sale price (Decimal number without currency symbol). Ex: 50.10 . The product
price can not exceed USD $1000.00
● quantity: Product quantity Integer (Max quantity 999)
● merchant_shipping_cost: Domestic shipping cost for DDP (Decimal number without currency
symbol). Could be 0. Ex: 9.99
● international_shipping_cost_by_country: Array of international shipping cost by country (only for
DDU). If international shipping cost for a country is provided, flat international shipping cost will be
ignored.
● estimated_delivery_time: Estimated delivery time of product (in days)
● weight_unit: Weight unit. Ex: lb or kg
Product API - Add Product 3/6

Regular product
● package_weight: Product package weight (Decimal without unit). Ex: 2.0
● dimension_unit: Dimension unit in or cm
● package_width: Product package width (Decimal without unit). Ex: 2.0
● package_height: Product package height (Decimal without unit). Ex: 2.0
● package_length: Product package length (Decimal without unit). Ex: 2.0
● condition: Product condition New or used or refurbished

In the response, you will receive the MercadoLibre product id (mpid) with other product details of the newly
created product. The mpid can be used as unique reference for this product.
Product API - Add Product 4/6

Regular product example

Request Response
[POST]
https://api-cbt.mercadolibre.com/api/SKUs/validate?a HTTP 200 OK, if no error.
ccess_token=xxxxxxxxx {
Header: Content-Type:application/json
“mpid”: “9000003352”,
Body (JSON):
{ “status”: “pending_processing”,
“SKU”: “01428510”, “sku”: “01428510”,
“product_type”: “Women Sunglass”, …
“product_title_english”: “Product title in English”, }
....
}
OR HTTP error code with error message
 Product API - Add Product 5/6

Product with variations

In order to publish a product with variation, you must create a parent product and multiple child product as
much as you need.

To use variations, you must send us the SKU for the parent product and for the child SKUs. Then you should
include the attribute ID and attribute value for each child SKU.

Attributes are used when your product has multiple variations such as different colors for the same product or
different sizes, etc.

The parent SKU is the SKU of the main product (say "XYZ_PRIMARY") you are trying to list, which has
"children" (variations of color, size, etc.). For example, if you are listing a shoe, the main shoe would be a
parent, and each size would be a child SKU. For each child, you would include the attribute ID and value for
each size.
 Product API - Add Product 6/6

Besides the all required to add a regular product, you must include specific fields for parent and children
SKU.
Parent SKU required fields: Child SKU required fields:

sku: ZXA123 sku: ZXA123_CHILD

is_primary_variation: 1 primary_variation_sku: ZXA123
is_primary_variation: 0
“variation”:[
{
“id”:”33000”,
“value_id”:”43000”
},
{
“id”:”33002”,
“value_id”:”43000”
}
]
 Product API - Translation

We recommend build the titles with the following structure:

Product Name + Brand + Model + Technical specifications and characteristics + additional services
Also, we recommend include all this information in 60 characters in product title english
If you provide the product content in English, we will You can provide the product data in Portuguese and Spanish.
take care of the translation. But is still required that you provide the product data in
English.

Fields required to provide us product data in Portuguese and

Fields required: Spanish:
● product_title_english ● product_title_english ● specification_english
● description_english ● product_title_portuguese ● specification_portuguese
● product_title_spanish ● specification_spanish
● description_english ● translation_required = 1
● description_portuguese
● description_spanish
Product API - Product Status

The product statuses are:

● pending_processing: The product is in queue, pending to processing on CBT platform.
● translation_complete: The product was translated, and it is waiting to finish the classification process.
● classification_complete: The product was classificated, and it is waiting to finish the translation process.
● ready_to_publish: The product is ready to publish in Mercado Libre.
● published: The product is published in Mercado Libre.
● out_of_stock: The product does not have stock and does not show in Mercado Libre.
● deleted: The product was deleted from the platform.
Product API - Publish Product (unpublish)

When the product is on status “ready_to_publish”, you must perform a request to finish publishing the product
in Mercado Libre. Once this task will have processed, the product will be on status “published”. The value of
params publish_to_BR, publish_to_MX, indicates the publish status. 1 for Publish, 0 for Unpublish.

Request Response
[PUT] HTTP 200 OK, if listing was successful.
https://api-cbt.mercadolibre.com/api/SKUs/<mpid> OR HTTP error code with error message
/?access_token=xxx {
"error":[
Header: Content-Type:application/json
{ "id":10094,
Body (JSON): "code":"CHILD_QUANTITY_REQUIRED",
{ "message":"Quantity should be greater than zero for
“publish_to_BR”: 1, atleast one child product"
}
“publish_to_MX”: 1 ]
} }
Product API - Update Product 1/3

Regular Update
For update an existing product on MercadoLibre you must use the mpid, returned in Add Product response.
Except SKU and category_id, all the fields for a product can be updated using mpid.
Request Response
[PUT]
HTTP 200 OK, if no error.
https://api-cbt.mercadolibre.com/api/SKUs/<mpid>/?access
{
_token=xxx
Header: Content-Type:application/json “mpid”: “9000003352”,
Body (JSON): “status”: “pending_processing”,
{ “sku”: “01428510”,
“SKU”: “01428510”, …
“primary_variation_sku “: “women sunglass”, }
“product_title_english”: “Optional product title in English”
... OR HTTP error code with error message
}
Product API - Update Product 2/3

Update Price and Quantity

This update mechanism is used for updating only the price, quantity, and shipping cost. If product quantity is
zero, the product will be marked as ‘unavailable’ and all listings on MercadoLibre sites will be ended.
For an unavailable product, if product quantity is greater than 0, the product will be marked as available and it
will be relisted on MercadoLibre sites.
If you update price and quantity on the primary SKU will be ignored and API won’t throw any error.
The fields accepted are:
● sale_price (Optional)
The product price can not exceed
● merchant_shipping_cost (Optional) USD $1000
● international_shipping_cost (Optional)
● international_shipping_cost_by_country (Optional)
● quantity (Optional)
Product API - Update Product 3/3

Update Price and Quantity Example

Request Response
[PUT]
HTTP 200 OK, if no error.
https://api-cbt.mercadolibre.com/api/SKUs/<mpid>/?access
{
_token=xxx
Header: Content-Type:application/json “mpid”: “9000003352”,
Body (JSON): “status”: “pending_processing”,
{ “sku”: “01428510”,
“sale_price”: 135, …
“merchant_shipping_cost”: 5, }
"international_shipping_cost": 15.00,
“quantity”: 10 OR HTTP error code with error message
}
Product API - Other considerations

● Prohibited products
● Product Dimensions Limit
 Listings in Merchant Portal

Products Listings

Clicking on drop
down, you can see
the active item id
published in each
site
 Orders API

In order to manage orders, you must take into account the following topics:

1. Order Flow
a. Get Order
b. Cancel Order
 Orders API - Order Flow

1. Order Flow

When you sale a product in Mercado Libre, you will get a notification to notify you.
At that moment, you can get the order via API.

In the order you can find the shipment label: In the parameter “shipment_label_location” . Ex:
“shipment_label_location”:"https:\/\/cbt.mercadolibre.com\/label\/lcq_V2aUv5z1Qg"

Also you can get the Invoice in the following endpoint:

https://api-cbt.mercadolibre.com/api/orders/<order_id>/invoice?access_token=XXX . You must print
three copies of the invoice. The first, to put on the package, the second and the third, to give to carrier.

To perform the shipping, please check the Shipment API indications.

Orders API - Get Order

a. Get Order

Request Response
[GET]
HTTP 200 OK, if no error.
https://api-cbt.mercadolibre.com/api/orders/<orderid>/?acc
{
ess_token=xxx
Header: Content-Type:application/json “order_id”:”DBR5353453535”,
“status”:”confirmed”,
“payment_status”:”confirmed”,
“created_date”:”Order creation date”,
…
}

OR HTTP error code with error message

Orders API - Cancel Order

b. Cancel Order

Request Response
[PUT] HTTP 200 OK, if no error.
https://api-cbt.mercadolibre.com/api/orders/<orderi {
d>/?access_token=xxx
Header: Content-Type:application/json “order_id”:”DBRXXXXX”,
Body (JSON): “status”:”cancelled”
{ }
“status”: “cancelled”
} OR HTTP error code with error message
 Orders in Merchant Portal

Sales Orders
 Order details in Merchant Portal

Orders View details

 Shipment API

In order to manage orders, you must take into account the following topics:

1. Shipment Flow
a. Drop Off and Pick up instructions
i. Create Shipment
b. Warehouse
c. Drop off notification
d. Tracking your packages
Shipment API - Shipment Flow

[POST] Create Shipment

Request
https://api-cbt.mercadolibre.com/api/shipment
Pick up
s/?access_token=xxx (7.a. Create Shipment)

Once you have printed

the shipping label and Or
invoices
Drop the package off at a DHL facility
Drop off You don’t need do anymore!
Shipment API - Drop Off and Pick up instructions

Drop off option

1. Print the label we display in the order and put it on the package.
2. Drop the package off at a DHL facility. DO NOT "Create Shipment". Once DHL receives the package our system will
mark it as Shipped automatically and update the tracking info.

Pick-up option
1. Print the label we display in the order and put it on the package.
2. You must need "Create Shipment" through API.
3. DHL will pick it up at your warehouse.

Note:All the products placed in order need to be sent with the same shipping label.
 Shipment API - Create Shipment (only for Request Pick up)

In order to request the product pickup you need to create a shipment with the following information:

The fields accepted are:

● order_id: The order id
● carrier: Shipment carrier. Just use “DHL”

For more informations see (7.a. Create Shipment)

 Shipment API - Request Pick Up and Create Shipment 2/2

Request Response
[POST] https://api-cbt.mercadolibre.com/api/shipments/?access_token=xxx HTTP 200 OK, if no error.
Header: Content-Type:application/json {
Body (JSON): "shipment_details": {
{
"shipment_id": 523,
"order_id":"DBR5591409660214",
"shipment_status": "pending"
"carrier":"DHL"
}
}
}

OR HTTP error code with error message

 Shipment API - Tracking your packages

Mercadolibre DHL
https://cbt.mercadolibre.com/trk/[order_id] for example: http://www.dhl.com/en/express/tracking.html?AWB=1734759552
https://cbt.mercadolibre.com/trk/DMX1258472840 &brand=DHL
Shipment API - Cancel Shipment

If you need cancel shipment (only for status pending) or you need require a new label shipment, you must
send an email to CBT Mercado Libre Operations (cbt-support@mercadolibre.com)

Request Response
[PUT] HTTP 200 OK, if no error.
https://api-cbt.mercadolibre.com/api/shipments/<s
hipmentid>?access_token=xxx OR HTTP error code with error message
Header: Content-Type:application/json
Body (JSON): Cancel shipment won’t be allowed if the
{ package is delivered to warehouse
“status”: “cancelled”
}
 Pre-Sales and post-sale questions

Questions Pre-sale and Post-sale

Machine translated
 Pre-Sales and Post-sale Questions with local Meli APIs

We can provide a mechanism for managing pre sale question and post sale messages
using the local Mercadolibre APIs.

This solution doesn’t include the translation module so you need to take care translations
for each site.
For more information please contact cbt-support@mercadolibre.com
 Claims

Summary Claims

From the Summary you find

this block where you can
access directly to Claims
 Claims

Open claim Answer claims

You can manage your claims by replaying the buyer messages or doing a refund.
 Contact Us

Mercado Libre
e-mail

Support operation cbt-support@mercadolibre.com