Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Sales
References
A - Receive notification and obtain specific information
about the order
B - Verify the existence of tag "pack_order" in the order
C - Check if the order has an associated shipment
D - Obtain the shipping items (they may correspond to
different orders)
E - Validate the order quantity of the shipment
F - Get the information of the orders associated with the
shipment
G - Get shipping information
Receive an order
Once a new order is created on your user, you can check its details by making
a request to the order resource. We recommend you subscribe to
orders_feedback
the new topic to receive updates on feedbacks.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_IDExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/2000003508419013 Response:
{
"id": 2000003508419013,
"status": "paid",
"status_detail": null,
"date_created": "2013-05-27T10:01:50.000-04:00",
"date_closed": "2013-05-27T10:04:07.000-04:00",
"order_items": [{
"item": {
"id": "MLB12345678",
"title": "Samsung Galaxy",
"variation_id": null,
"variation_attributes": []
},
"quantity": 1,
"unit_price": 499,
"currency_id": "BRL"
}],
"total_amount": 499,
"currency_id": "BRL",
"buyer": {
"id": "123456789",
"nickname": "COMPRADORTESTE",
"first_name": "Comprador de testes",
"last_name": "da Silva",
},
"seller": {
"id": "123456789",
},
"payments": [{
"id": "596707837",
"transaction_amount": 499,
"currency_id": "BRL",
"status": "approved",
"date_created": null,
"date_last_modified": null
}],
"feedback": {
"purchase": null,
"sale": null
},
"context": {
"channel": "marketplace",
"site": "MLB",
"flows": [
000]
},
"shipping": {
"id": 20676482441
},
"tags": [
"paid",
"not_delivered"
]
}Response fields:
id: unique order identifier.
date_created: order creation date.
date_closed: order confirmation date. It is set when an order
status changes for the first time to confirmed / paid and the item is
subtracted from the stock.
expiration_date: this is the deadline for the user to qualify
since, after that date, the feedback is made visible, payments are released
(if any), and charges are created.
status: order status. See possible values.
status_detail: status detail.
code: status code.
description: status description.
buyer: buyer's information.
seller: seller's information.
order_items: order item listings.
- item: specific listing.
- quantity: quantity of items purchased.
- sale_fee: sales commission.
- unit_price: price per item.
payments: order-related payments.
feedback: ID feedback information.
context: detail of the characteristics of the creation of an
order.
- channel: current sales channels for the item. possible values: mshops | proximity | mp-channel | marketplace.
- site: ID of the site where the purchase originated (MLA, MLB, MLM, etc).
- flows: is a list of characteristics of the origin of the purchase. Possible values cbt | subscription | reservation | reservation | catalog, contract | supermarket | 3x_campaign | high_concurrency | lite.
- group: logical grouping of cancellation (mediations, fiscal, buyer, fraud, item, shipment, delivery, seller, internal).
- code: cancellation cause code.
- description: description of the cause of cancellation.
- requested_by: who requests the cancellation (buyer, seller, Mercado Libre).
- date: cancellation date.
- application_id: ID of the application requesting cancellation.
shipping: ID shipping for this order.
total_amount: total invoice amount.
currency_id: currency ID.
tags: list of seller selected tags, such as delivered,
paid.
taxes: amount with the sum of taxes to be paid from the
order.
cancel_detail. detail of the cancellation of
the order in which it is found.
Fraud alerts (stop shipping)
After the payment approval, and due to the relationship with banks and
cards, we may receive an alert that the order is a fraud and to avoid a
financial expense, you shouldn´t send the merchandise to the buyer.
In this case,
or order is marked with the tag "fraud_risk_detected" and
we send a notification with the topic "orders_v2" with the ID of this order.
Once identified, the order must be canceled. Case the seller has already
been sent products, it will be necessary to check or send it through the
Mercado Libre or Mercado Pago sites.
Total_amount_with_shipping calculation
With the response that you get in the GET /orders/:id request and the request to GET /shipments/:shipping_id resource, both with the header x-format-new: true, you have to do the next calculation:
| total_amount_with_shipping = total_amount + taxes.amount + lead_time.cost |
|---|
*With the same item currency.
The total_amount and taxes.amount are obtained by the /orders resource, and the lead_time.cost resource is obtained from the /shipments.
Request:
curl -X GET https://api.mercadolibre.com/currency_conversions/search?from=$CURRENCY_ID&to=$CURRENCY_IDExample:
curl -X GET https://api.mercadolibre.com/currency_conversions/search?from=ARS&to=BRLResponse:
{
"ratio": 0.0704988
}
What will happen to a sale based on its delivery?
Without Mercado Envíos: The seller will be notified by e-mail or phone.
- If the item has already been delivered and there is evidence of that, the seller is covered in the event of a chargeback. This means that the sales money will not be deducted.
- If the item has not been delivered yet, the seller should refund the money.
- Learn how to make a refund via API in Refunds and cancellations.
- For more information, we suggest reading the documentation of “Seller Protection Program Requirements”.
With Mercado Envíos: If the label has not been printed yet, the sale will be cancelled and a notification will be sent to the seller. Otherwise, if the item has already been shipped, Mercado Libre will notify the shipping company to return the item.
Search orders
You can use the /search functionality of the /orders resource to make searches with filters. Note that /search does not perform any action if it is not followed by a filter.
You will be able to see those orders canceled manually, that is, with status manually_cancelled and those that have an item removed, using the search as buyer. If you search as a seller, you will continue to filter such (canceled) orders.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?buyer=$BUYER_IDExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?buyer=89660613&q=2032217210Response:
{
"query": "2032217210",
"results": [
{
"seller": {
"phone": {
"number": "11971427863",
"extension": "",
"area_code": null,
"verified": false
},
"alternative_phone": {
"number": "",
"extension": "",
"area_code": ""
},
"nickname": "VENDASDKMB",
"last_name": "Cheracomo",
"id": 239432672,
"first_name": "Demétrio",
},
"payments": [
{
"reason": "Kit Com 03 Adesivo Spray 3m 75 Cola Silk Sublimação 300g",
"status_code": null,
"total_paid_amount": 129.95,
"operation_type": "regular_payment",
"transaction_amount": 129.95,
"date_approved": "2019-05-22T03:51:07.000-04:00",
"collector": {
"id": 239432672
},
"coupon_id": null,
"installments": 1,
"authorization_code": "008877",
"taxes_amount": 0,
"id": 4792155710,
"date_last_modified": "2019-05-22T03:51:07.000-04:00",
"coupon_amount": 0,
"available_actions": [
"refund"
],
"shipping_cost": 0,
"installment_amount": 129.95,
"date_created": "2019-05-22T03:51:05.000-04:00",
"activation_uri": null,
"overpaid_amount": 0,
"card_id": 203453778,
"status_detail": "accredited",
"issuer_id": "24",
"payment_method_id": "master",
"payment_type": "credit_card",
"deferred_period": null,
"atm_transfer_reference": {
"transaction_id": "135292",
"company_id": null
},
"site_id": "MLB",
"payer_id": 89660613,
"marketplace_fee": 14.290000000000001,
"order_id": 2000003508419013,
"currency_id": "BRL",
"status": "approved",
"transaction_order_id": null
}
],
"fulfilled": true,
"buying_mode": "buy_equals_pay",
"taxes": {
"amount": null,
"currency_id": null
},
"order_request": {
"change": null,
"return": null
},
"expiration_date": "2019-06-19T03:51:07.000-04:00",
"feedback": {
"sale": null,
"purchase": null
},
"shipping": {
"id": 27968238880
},
"date_closed": "2019-05-22T03:51:07.000-04:00",
"id": 2032217210,
"manufacturing_ending_date": null,
"hidden_for_seller": false,
"order_items": [
{
"item": {
"seller_custom_field": null,
"condition": "new",
"category_id": "MLB33383",
"variation_id": null,
"variation_attributes": [],
"seller_sku": null,
"warranty": "Garantia de 1 ano fabricante",
"id": "MLB1054990648",
"title": "Kit Com 03 Adesivo Spray 3m 75 Cola Silk Sublimação 300g"
},
"quantity": 1,
"differential_pricing_id": null,
"sale_fee": 14.29,
"listing_type_id": "gold_special",
"base_currency_id": null,
"unit_price": 129.95,
"full_unit_price": 129.95,
"base_exchange_rate": null,
"currency_id": "BRL",
"manufacturing_days": null
}
],
"date_last_updated": "2020-02-14T02:55:49.811Z",
"last_updated": "2019-05-28T15:16:04.000-04:00",
"comments": null,
"pack_id": null,
"coupon": {
"amount": 0,
"id": null
},
"shipping_cost": 0,
"date_created": "2019-05-22T03:51:05.000-04:00",
"application_id": "7092",
"pickup_id": null,
"status_detail": null,
"tags": [
"delivered",
"paid"
],
"buyer": {
"phone": {
"number": "99962663",
"extension": "",
"area_code": "41",
"verified": false
},
"alternative_phone": {
"number": "30576339",
"extension": "",
"area_code": "41"
},
"nickname": "S.VICTORHUGO",
"last_name": "Schemberger",
"id": 89660613,
"first_name": "Victor Hugo",
},
"total_amount": 129.95,
"paid_amount": 129.95,
"mediations": [],
"currency_id": "BRL",
"status": "paid"
}
],
"sort": {
"id": "date_asc",
"name": "Date ascending"
},
"available_sorts": [
{
"id": "date_desc",
"name": "Date descending"
}
],
"filters": [],
"paging": {
"total": 1,
"offset": 0,
"limit": 50
},
"display": "complete"
}
Products information in orders
This request shows all the information of the products that are in the same order:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$order_id/productResponse:
{
"attributes": [
{
"name": "IMEI",
"value": "111",
"id": 1
},
{
"name": "IMEI",
"value": "222",
"id": 2
},
{
"name": "entry_date",
"value": "01/01/2001",
"id": 3
}
]
}
Get discounts applied to a sale
Use the /discounts resource to review the details of all the discounts that have impacted a sale. Remember that discounts can come from a campaign (promotion), a coupon or cashback, and that a sale can have more than one discount applied.
Remember that orders created up to 12 months ago are currently saved, and if you search as a seller, canceled orders will be filtered out.
Request:
curl -X GET -H ‘Authorization: Bearer $ACCESS_TOKEN’ https://api.mercadolibre.com/orders/$ORDER_ID/discountsExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/2000003508419013/discountsResponse:
{
"details": [
{
"type": "coupon",
"coupon": {
"id": 569290732
},
"supplier": {
"meli_campaign": "P-MLA4944001"
},
"items": [
{
"quantity": 1,
"amounts": {
"total": 446.7,
"seller": 0
},
"id": "MLA922971037"
}
]
},
{
"type": "discount",
"supplier": {
"offer_id": "MLA922971037-abc123",
"funding_mode": "sale_fee"
},
"items": [
{
"quantity": 1,
"amounts": {
"total": 446.7,
"seller": 0
},
"id": "MLA922971037"
}
]
},
{
"type": "cashback",
"items": [
{
"element_id": 1,
"quantity": 1,
"id": "MLB1881365644",
"amounts": {
"total": 5.4,
"seller": 0
}
}
],
"supplier": {
"campaign_id": "10116144"
},
"cashback": {
"id": "2251800174114906"
},
"counter_currency": {
"currency_id": "MCN",
"value": 15.6784541
}
}
]
}Response fields
Each discount can have the following fields within the details attribute, depending on the type:
- coupon.id: Coupon identifier.
- supplier: Campaign provider.
- meli_campaign: Discount campaign associated with the coupon.
- offer_id: Offer identifier, useful for retrieving the campaign name.
- funding_mode: Type of promotion obtained by the IPA. For example, sale_fee.
- items: Items to which the coupon applies.
- id: Item identifier.
- quantity: Quantity of items affected by the discount.
- amounts: Coupon values.
- total: Portion of the discount associated with the item (p * q).
- seller: Portion of the discount for the seller (p * q).
Filter
To filter your orders with status "paid" accounts with the following filters:
item: tittle ID
tags: it can be some status separated by ','
tags.not: it can be some status separated by ','
q: it is a field that allows you to search by:
- order id
- item id
- item title
- nickname of the counterpart
order.status: it can be some status separated by ','
order.date_last_updated.from
order.date_last_updated.to
order.date_created.from
order.date_created.to
order.date_closed.from
order.date_closed.to
mediations.stage: it can be some status separated by ','
mediations.status: it can be some status separated by ','
feedback.status: it can be some status separated by ','
feedback.sale.rating: it can be some status separated by
','
feedback.sale.fulfilled
feedback.purchase.rating: it can be some status separated
by ','
feedback.purchase.fulfilled
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=seller_id&order.status=paid
If you want to filter your orders by date, you should do the following:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=$SELLER_ID&order.date_created.from=2015-07-01T00:00:00.000-00:00&order.date_created.to=2015-07-31T00:00:00.000-00:00
Sort
In this case, you should add “sort” to the available sort ID that you wish to apply, for example: “date_desc”.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller={seller_id}&order.status=paid&sort=date_desc
Mercado Shops Orders
Mercado Shops orders are also available in Mercado Libre API.
To identify these orders, you should use the tag "mshops".
Example of Mercado Shops orders:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-format-new: true' https://api.mercadolibre.com/orders/$ORDER_ID
{
"id": 2063200914,
"date_created": "2019-06-24T15:53:04.000-04:00",
"date_closed": "2019-06-24T15:53:06.000-04:00",
"last_updated": "2019-06-24T15:53:06.000-04:00",
"manufacturing_ending_date": null,
"feedback": {
"sale": null,
"purchase": null
},
"mediations": [],
"comments": null,
"pack_id": null,
"pickup_id": null,
"order_request": {
"return": null,
"change": null
},
"fulfilled": null,
"total_amount": 25,
"paid_amount": 31.9,
"coupon": {
"id": null,
"amount": 0
},
"expiration_date": "2019-07-22T15:53:06.000-04:00",
"order_items": [
"item": {
"id": "MLB1231068128",
"title": "Teste Anúncio Me2 - Não Ofertar",
"category_id": "MLB271107",
"variation_id": null,
"seller_custom_field": null,
"variation_attributes": [],
"warranty": null,
"condition": "new",
"seller_sku": null
},
"quantity": 1,
"unit_price": 25,
"full_unit_price": 25,
"currency_id": "BRL",
"manufacturing_days": null
],
"currency_id": "BRL",
"payments": [
"id": 4898000077,
"order_id": 2000003508419013,
"payer_id": 419067349,
"collector": {
"id": 419059118
},
"card_id": 313381752,
"site_id": "MLB",
"reason": "Teste Anúncio Me2 - Não Ofertar",
"payment_method_id": "master",
"currency_id": "BRL",
"installments": 1,
"issuer_id": "24",
"atm_transfer_reference": {
"company_id": null,
"transaction_id": "1234567"
},
"coupon_id": null,
"activation_uri": null,
"operation_type": "regular_payment",
"payment_type": "credit_card",
"available_actions": [
"refund"
],
"status": "approved",
"status_code": null,
"status_detail": "accredited",
"transaction_amount": 25,
"taxes_amount": 0,
"shipping_cost": 6.9,
"coupon_amount": 0,
"overpaid_amount": 0,
"total_paid_amount": 31.9,
"installment_amount": 31.9,
"deferred_period": null,
"date_approved": "2019-06-24T15:53:05.000-04:00",
"authorization_code": "1234567",
"transaction_order_id": null,
"date_created": "2019-06-24T15:53:05.000-04:00",
"date_last_modified": "2019-06-24T15:53:05.000-04:00"
],
"shipping": {
"id": 28001747957
},
"status": "paid",
"status_detail": null,
"tags": [
"mshops",
"test_order",
"not_delivered",
"paid"
],
"buyer": {
"id": 419067349,
"nickname": "TT763866",
"first_name": "Test",
"last_name": "Test",
"seller": {
"id": 419059118,
"nickname": "TETE8288849",
"phone": {
"area_code": "01",
"extension": "",
"number": "1111-1111",
"verified": false
},
"alternative_phone": {
"area_code": "",
"extension": "",
"number": ""
},
"first_name": "Test",
"last_name": "Test"
},
"taxes": {
"amount": null,
"currency_id": null
}The JSON structure is the same that Mercado Libre orders. Market Shops orders can also be made by cart. For this, refer to the Shopping cart orders documentation.
Get Mercado Shops orders
To consult the Marcado Shops orders, just consult by the tag mshops as in the following example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=seller_id&tags=mshops
Order status
Order statuses are the following:
confirmed Initial status of an order, even if it is still
unpaid.
payment_required Order payment should be confirmed to
display user information.
payment_in_process There is an order-related payment, but
it has not been credited yet.
partially_paid The order have a credited associated
payment, but it is not enough.
paid The order-related payment is credited, but it is not
enough.
cancelled For some reason, the order was not fulfilled.*
invalid The order was invalidated as it came from a
malicious buyer.
Error code reference
| Error | Error message | Description | Possible solution |
|---|---|---|---|
| order_not_found | Order not found. | $order_id incorrect. | The order cannot be found, check if the order_id is correct. More information. |
| empty_order_id | Order ID can not be empty. | $order_id is null. | The parameter order_id cannot be null, check the URL used. More information |
| invalid_order_id | Invalid order ID. | $order_id incorrect. | The parameter order_id must be a integer number. For search your orders see this topic. |
| not_identified_user | Can not identify the user. | Do not exist a Token. | Send a token. |
| not_owned_order | The user has not access to the order. | $seller or $buyer incorrect. | To see one order, your access_token must be generated from seller or buyer. |
| caller.id.invalid | caller.id does not match buyer nor seller. | $seller or $buyer incorrect. | To see one order, you must be use one ID from seller or buyer. |
| feedback_not_found | The feedback does not exist. | Reply error. | Check if feedback exist for give a reply. |
| invalid_fulfilled | ‘fulfilled’ parameter must be true or false. | Error on give feedback. | Check the parameter $fulfilled this must be boolean (remove quotation marks) and check if the parameter $reason is not null in case of $fulfilled: false. |
| reply_time_expired | Reply time expired. There is a 14 days period to reply a feedback. | Error on give reply on feedback. | The reply can be sent in 14 days past the feedback date. |
| reply_already_exists | Reply already exists for the feedback. | Error on give reply on feedback. | The feedback supports only one reply. |
HTTP response code references
Orders may return the code http 206 when it has not been possible to obtain
any data. Keep in mind that in most cases the information you receive will
be enough for you to continue working.
In the response header X-Content-Missing you will have the name of the
fields without information, which can be "buyer", "feedback", "mediations",
"seller" and / or "shipping".
Request::
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID
Response:
< HTTP/1.1 206 Partial Content> X-Content-Missing: buyer, feedback
{
"id": 768570754,
"status": "paid",
"status_detail": null,
"date_created": "2013-05-27T10:01:50.000-04:00",
"date_closed": "2013-05-27T10:04:07.000-04:00",
"order_items": - [
- {
"item": - {
"id": "MLB12345678",
"title": "Samsung Galaxy",
"variation_id": null,
"variation_attributes": [
],
},
"quantity": 1,
"unit_price": 499,
"currency_id": "BRL",
},
],
"total_amount": 499,
"currency_id": "BRL",
"buyer": - { },
},
"seller": - {
"id": "123456789",
},
"payments": - [
- {
"id": "596707837",
"transaction_amount": 499,
"currency_id": "BRL",
"status": "approved",
"date_created": null,
"date_last_modified": null,
},
],
"feedback": - { },
"shipping": - {
"id": 20676482441
},
"tags": - [
"paid",
"not_delivered",
],
}
Next:
Messaging after sale.