Merchant Portal Guide - API Version 1.0.0
Login
Link: https://cbt.mercadolibre.com/ https://cbt.mercadolibre.com/secure/login/merchan secure/login/merchant/ t/
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
[email protected]
Nombre
[email protected]
My Account - Email notifications My account
Notifications
[email protected]
[email protected]
[email protected]
[email protected]
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. 2. 3. 4.
Account Registr ation: you can request for a productive account thru our support channel
[email protected] CBT Application Creation Application Authorization (generate auth code) 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
[email protected].
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
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:
4.
Request
Response
[POST] https://api-cbt.mercadolibre.com/oauth/token Header: Content-Type:application/json Body (JSON):
{ "access_token": "xxxxxxxxxx", "expires_in": 172800, "token_type": "bearer", "scope": "read write offline_access", "refresh_token": "xxxxxxxxxx", "email": "
[email protected]"
{ "client_id": "xxxxx", "client_secret": "xxxxx", "grant_type": "authorization_code", "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", "grant_type": "refresh_token", "refresh_token": "xxxxxxxxx"
{ "client_id": "xxxxx", "client_secret": "xxxxx", "grant_type": "refresh_token", "refresh_token": "xxxxx" }
}
Product API
In order to publish items, you must take into account the following topics: 1. 2. 3. 4. 5. 6. 7. 8.
Categorization Product Validation Add Product a. Regular product b. Product with variations Translation Product Statuses Publish Product (unpublish) Update Product 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] https://api-cbt.mercadolibre.com/api/SKUs/validate?a ccess_token=xxxxxxxxx Header: Content-Type:application/json Body (JSON):
HTTP 200 OK, if no error. OR HTTP error code with error message like this
{ “SKU”: “01428510”, “product_type”: “Women Sunglass”, “product_title_english”: “Product title in English”,
{ “error”:[ { “id”:1005, “code”:”INVALID_CATEGORY_ID”, “message”:”A valid leaf level category id is require d “ } ] }
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 [POST] https://api-cbt.mercadolibre.com/api/SKUs/validate?a ccess_token=xxxxxxxxx Header: Content-Type:application/json Body (JSON): { “SKU”: “01428510”, “product_type”: “Women Sunglass”, “product_title_english”: “Product title in English”, .... }
Response HTTP 200 OK, if no error. { “mpid”: “9000003352”, “status”: “pending_processing”, “sku”: “01428510”, … }
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
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. Child SKU required fields: Parent SKU required fields: sku: ZXA123 is_primary_variation: 1
sku: ZXA123_CHILD 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 take care of the translation.
You can provide the product data in Portuguese and Spanish. But is still required that you provide the product data in English.
Fields required: ● product_title_english ● description_english
Fields required to provide us product data in Portuguese and Spanish: ● specification_english ● product_title_english specification_portuguese ● product_title_portuguese ● ● specification_spanish ● product_title_spanish ● translation_required = 1 ● description_english ● 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] https://api-cbt.mercadolibre.com/api/SKUs/
/?access_token=xxx Header: Content-Type:application/json Body (JSON): { “publish_to_BR”: 1, “publish_to_MX”: 1
HTTP 200 OK, if listing was successful. OR HTTP error code with error message { "error":[ { "id":10094, "code":"CHILD_QUANTITY_REQUIRED", "message":"Quantity should be greater than zero for atleast one child product" } ]
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] https://api-cbt.mercadolibre.com/api/SKUs//?access _token=xxx Header: Content-Type:application/json Body (JSON): { “SKU”: “01428510”, “primary_variation_sku “: “women sunglass”, “product_title_english”: “Optional product title in English”
HTTP 200 OK, if no error. { “mpid”: “9000003352”, “status”: “pending_processing”, “sku”: “01428510”, … } 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 [PUT] https://api-cbt.mercadolibre.com/api/SKUs//?access _token=xxx Header: Content-Type:application/json Body (JSON): { “sale_price”: 135, “merchant_shipping_cost”: 5, "international_shipping_cost": 15.00, “quantity”: 10 }
Response HTTP 200 OK, if no error. { “mpid”: “9000003352”, “status”: “pending_processing”, “sku”: “01428510”, … } 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 or der 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//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 [GET] https://api-cbt.mercadolibre.com/api/orders//?acc ess_token=xxx Header: Content-Type:application/json
Response HTTP 200 OK, if no error. { “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] https://api-cbt.mercadolibre.com/api/orders//?access_token=xxx Header: Content-Type:application/json Body (JSON): { “status”: “cancelled” }
HTTP 200 OK, if no error. { “order_id”:”DBRXXXXX”, “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
Once you have printed the shipping label and invoices
Request Pick up
[POST] Create Shipment https://api-cbt.mercadolibre.com/api/shipment s/?access_token=xxx (7.a. Create Shipment)
Drop off
Drop the package off at a DHL facility You don’t need do anymore!
Or
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 [POST] https://api-cbt.mercadolibre.com/api/shipments/?access_token=xxx Header: Content-Type:application/json Body (JSON): { "order_id":"DBR5591409660214", "carrier":"DHL" }
Response HTTP 200 OK, if no error. { "shipment_details": { "shipment_id": 523, "shipment_status": "pending" } } OR HTTP error code with error message
Shipment API - Tracking your packages
Mercadolibre
DHL
https://cbt.mercadolibre.com/trk/[order_id] for example: https://cbt.mercadolibre.com/trk/DMX1258472840
http://www.dhl.com/en/express/tracking.html?AWB=1734759552 &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 ([email protected])
Request
Response
[PUT] https://api-cbt.mercadolibre.com/api/shipments/?access_token=xxx Header: Content-Type:application/json Body (JSON): { “status”: “cancelled” }
HTTP 200 OK, if no error. OR HTTP error code with error message Cancel shipment won’t be allowed if the package is delivered to warehouse
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 [email protected]
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.
