Manage Sales

An order is a request a customer places on a listed item with the intention to purchase it under a series of conditions he/she will choose throughout the checkout flow.
These conditions are detailed on the order that will be replicated for the buyer and the seller accounts as well. On the order you’ll find a lot of information to fill out about your product and you’ll be able to reserve and/or subtract stock.

Contents:

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:
Example:

curl https://api.mercadolibre.com/orders/$ORDER_ID?access_token=$ACCESS_TOKEN

Response:

{
  "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": - {
	"id": "123456789",
	"nickname": "COMPRADORTESTE",
	"email": "b@b.com",
	"phone": - {
  	"area_code": "11",
  	"number": "12345678",
  	"extension": null,
	},
	"first_name": "Comprador de testes",
	"last_name": "da Silva",
	"billing_info": - {
  	"doc_type": "CPF",
  	"doc_number": "12345678910",
	},
  },
  "seller": - {
	"id": "123456789",
	"nickname": "VENDEDORTESTES",
	"email": "a@a.com",
	"phone": - {
  	"area_code": null,
  	"number": "11 12345678",
  	"extension": "11",
	},
	"first_name": "Vendedor de Testes",
	"last_name": "testes de documentacao",
  },
  "payments": - [
	- {
  	"id": "596707837",
  	"transaction_amount": 499,
  	"currency_id": "BRL",
  	"status": "approved",
  	"date_created": null,
  	"date_last_modified": null,
	},
  ],
  "feedback": - {
	"purchase": null,
	"sale": null,
  },
  "shipping": - {
	"id": 20676482441,
	"shipment_type": "shipping",
	"status": "handling",
    "date_created": "2013-05-27T10:03:28.000-04:00",
	"receiver_address": - {
  	"id": 12345678,
  	"address_line": "Rua dos testes 123  ",
  	"zip_code": "01001000",
  	"city": - {
    	"id": "BR-SP-44",
    	"name": "São Paulo",
  	},
  	"state": - {
    	"id": "BR-SP",
    	"name": "São Paulo",
  	},
  	"country": - {
    	"id": "BR",
    	"name": "Brasil",
  	},
  	"latitude": null,
  	"longitude": null,
  	"comment": null,
	},
	"currency_id": "BRL",
	"cost": 0,
  },
  "tags": - [
	"paid",
	"not_delivered",
  ],
}

Orders have a lot of attributes. Below you will see a description of the most important 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, in case the order is canceled.
code Status code.
description Status description.
comprador Buyer’s Information.
vendedor Seller’s information.
order_items Order item listings.
payments Order-related payments.
feedback Order-related feedback information.
shipping Shipping configuration for this order.
total_amount Total invoice amount.
currency_id Currency ID.
tags List of seller selected tags, such as delivered, paid.
Note: As it happens every time the information of an order is updated, if we discover a fraudulent purchase, we will place the “fraud_risk_detected” tag to the order and send you a notification with the topic “orders” and said order ID.

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.
  • To learn how to make a refund via API please see the relevant documentation.
  • 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

The search orders resource will help you browse every order that belongs to users for whom you have a valid token.

https://api.mercadolibre.com/orders/search?buyer=buyer_id&access_token={...}

The fields “available_filters” and “available_sorts” are available in search orders.
Take into account that the search does not show orders in Payment_required status.

How to filter?

For example, to filter your orders with “paid” status, you will find the “order.status” ID among the “available_filters,” and, in turn, you will find the value with “paid” ID in that field.

https://api.mercadolibre.com/orders/search?seller=seller_id&order.status=paid&access_token={...}

If you want to filter your orders by date, you should do the following:

https://api.mercadolibre.com/orders/search?seller=&order.date_created.from=2015-07-01T00:00:00.000-00:00&order.date_created.to=2015-07-31T00:00:00.000-00:00&access_token=

How to sort?

In this case, you should add “sort” to the available sort ID that you wish to apply, for example: “date_desc”.

https://api.mercadolibre.com/orders/search?seller={seller_id}&order.status=paid&sort=date_desc&access_token={...}

Note: By default, it sorts by date_asc. The sorting date is:

  • Sellers by date_closed.
  • Buyers by date_created.

Recent Orders

Recent orders are the latest orders that were generated for a user. The response will include orders in which the current date is before expiration_date, and haven’t been qualified by any of the parties.
Searching for a seller’s recent orders:

https://api.mercadolibre.com/orders/search/recent?seller=seller_id&access_token={...}

Searching for a buyer’s recent orders:

https://api.mercadolibre.com/orders/search/recent?buyer=buyer_id&access_token={...}

Archived Orders

If you are looking for an order with expiration_date after current date or which was qualified by both parties, you can use the search archived orders resource:
Searching for a seller’s archived orders:

https://api.mercadolibre.com/orders/search/archived?seller=seller_id&access_token={...}

Searching for a buyer’s archived orders:

https://api.mercadolibre.com/orders/search/archived?buyer=buyer_id&access_token={...}

Pending Orders

This search will retrieve all the orders with “pending” status, and will automatically skip canceled orders.
If you want to see a specific seller’s orders, send the seller_id:

https://api.mercadolibre.com/orders/search/pending?seller=seller_id&access_token={...}

To search by buyer, replace the parameters as follows:

https://api.mercadolibre.com/orders/search/pending?buyer=user_id&access_token={...}

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-related payment is credited, but it is not enough.
paid
The order-related payment is credited.
cancelled
For some reason, the order was not fulfilled.*
invalid
The order was invalidated as it came from a malicious buyer.

*Note:
An order may be canceled due to the following reasons:

  • Payment approval was required to subtract stock, but, during the approval process period, the item was paused/terminated due to stockout; so, the payment is returned to the buyer.
  • Payment was required, but, as it was not paid within a specific period, it was automatically canceled.
  • After making a transaction, for some reason the seller is banned from the site.
  • If for some reason the seller rates the transaction as non-completed, the order takes the “status = confirmed.” If there is an approved payment, it will be automatically returned.

    Bear in mind that an order that has not been completed by the seller at front will appear as “Cancelled” and with api “status: confirmed”.

Mandatory Mercado Pago Flow (only for countries with MP)

How to find out if a site has Mercado Pago enabled?
To get that information, call:

curl https://api.mercadolibre.com/sites/MLA

If you receive “MLAMP” as a response within “payment_method_ids,” you will be able to work smoothly with this flow.

Explanatory Note: MLAMP is Mercado Pago’s payment method ID:

curl https://api.mercadolibre.com/payment_methods/MLAMP

On our platform you will find orders which can go through Mercado Pago’s mandatory flow as the only payment method, and others which cannot.
This choice will be mandatory in the scenarios below:

  • All MLB orders
  • All MLA and MLM orders from the sale of products with “condition”: “new”
  • Official Store Listings in every country with Mercado Pago.
  • Categories with Mercado Pago as the only choice. (For more information, visit: “Immediate payment categories
  • User automatically marked to have transactions routed through this flow with the mark “immediate_payment” in the users API.
  • Seller “auto” marked to have sales routed through this flow.


Now we will explain the general operation of orders entered through this flow or otherwise:
1) Orders entered through this flow are created with a “payment_required” status.
And they have the following characteristics:

  • They are not visible to the seller.
  • The item is not subtracted from the stock.
  • The date_closed field is not filled out.
  • Counterpart data is not filled out.
  • Only the “created_orders” topic notification is sent.

When the total amount of the sale payment is credited, order status changes from “payment_required” to “paid.” At that time:

  • They become visible to the seller.
  • The item is subtracted from the stock.
  • The date_closed field is filled out.
  • The counterpart’s data is filled out.
  • The “orders” topic notifications start to be sent.


2) Orders NOT entered through this flow are created with a “confirmed” status. Starting at that time:

  • They are visible to the seller.
  • The item is subtracted from the stock.
  • The date_closed field is filled out.
  • The counterpart’s data is filled out.
  • The “orders”/“created_orders” topic notifications start to be sent.

If a payment made through Mercado Pago is credited for the total amount of the sale, order status changes from “confirmed” to “paid”.

Explanatory Note: In both cases, if the buyer selects Mercado Envíos (ME2, only in countries where this service is enabled) in the payment flow, the shipping will have the label ready to print once the order status changes to “paid.” More information.

How does your app become aware of a purchase?

The creation of an order is an event that occurs on MercadoLibre’s side, so you’ll need to subscribe to our orders feed to become aware in real time when that event occurs.
Go to our Application Manager and edit your application Notifications Settings. For more information about creating and configuring a new app, please check this link.
You must choose a Callback URL: configure the public URL of the domain where you want to receive all the notifications from MercadoLibre. For example:
The creation of an order is an event that occurs on MercadoLibre’s side, so you’ll need to subscribe to our orders feed to become aware in real time when that event occurs.
Go to our Application Manager and edit your application Notifications Settings. For more information about creating and configuring a new app, please check this link.
You must choose a Callback URL: configure the public URL of the domain where you want to receive all the notifications from MercadoLibre. For example: “https://backend.soleorigami.com/notification”.

ORDERS

This configuration allows you to interact with MercadoLibre notifications. All the events (like payments and shipping) related to an order will be notified to your callback URL.

Receive a Notification

Mercado Libre will send you notifications through a POST message with information in the listing body. The most important attribute in the message is the notification-related user_id, followed by the resource. The resource is the element which was updated or created.

{
  "user_id": 1234,
  "resource": "/orders/731867397",
  "topic": "orders",
  "received": "2011-10-19T16:38:34.425Z",
  "application_id" : 14529
  "sent" : "2011-10-19T16:40:34.425Z",
  "attempts" : 0
}

After receiving a notification, you must send an acknowledgment (ACK 200) to MercadoLibre in order to stop receiving it.

Payments

Mercado Pago is MercadoLibre’s payment platform. If you want to integrate a payment solution on your platform, you should check Mercado Pago’s developers’ website.

Multiple Payment Scenario

In some cases, when the payment is rejected for reaching the credit card limit, we let users add another payment with a second credit card.

How can I know if there are two payments?

When you make a GET to Orders API, you’ll see that there will be two IDs with the details of each payment in the payment array.

Example:

curl -X GET https://api.mercadolibre.com/orders/893431118?access_token=&ACCESS_TOKEN

Response:

{
	"buyer": {
    	"alternative_phone": {
        	"area_code": null,
        	"extension": null,
        	"number": ""
    	},
    	"billing_info": {
        	"doc_number": "67045427794",
        	"doc_type": "CPF"
    	},
    	"email": "test_user_21963158@testuser.com",
    	"first_name": "Test",
    	"id": 160903317,
    	"last_name": "Test",
    	"nickname": "TETE2022123",
    	"phone": {
        	"area_code": "01",
        	"extension": null,
        	"number": "1111-1111"
    	}
	},
	"coupon": {
    	"amount": 0,
    	"id": null
    },
	"currency_id": "BRL",
	"date_closed": null,
	"date_created": "2014-10-26T22:46:18.000-04:00",
	"feedback": {
    	"purchase": null,
    	"sale": null
	},
	"id": 893431118,
	"last_updated": "2014-10-26T22:50:10.000-04:00",
    "mediations": [],
	"order_items": [
    	{
        	"currency_id": "BRL",
        	"item": {
            	"id": "MLB600034093",
            	"title": "Item De Testeo, Por Favor No Ofertar --kc:off",
            	"variation_attributes": [],
            	"variation_id": null
        	},
        	"quantity": 1,
        	"unit_price": 591
    	}
	],
	"paid_amount": 591,
	"payments": [
    	{
        	"activation_uri": null,
        	"atm_transfer_reference": {
            	"company_id": null,
                "transaction_id": null
        	},
            "available_actions": [],
        	"card_id": null,
        	"collector": {
            	"id": 169648308
        	},
        	"coupon_amount": 0,
        	"coupon_id": null,
        	"currency_id": "BRL",
        	"date_created": "2014-10-26T22:48:46.000-04:00",
            "date_last_modified": "2014-10-27T00:51:53.000-04:00",
        	"id": 885920310,
        	"installments": 1,
        	"issuer_id": "25",
        	"operation_type": "regular_payment",
        	"order_id": 893431118,
        	"overpaid_amount": 0,
        	"payer_id": 160903317,
            "payment_method_id": "visa",
        	"payment_type": "credit_card",
        	"reason": "Item De Testeo, Por Favor No Ofertar --kc:off",
        	"shipping_cost": 0,
        	"site_id": "MLB",
        	"status": "approved",
        	"status_code": null,
        	"status_detail": "accredited",
            "total_paid_amount": 296,
            "transaction_amount": 296
    	},
    	{
        	"activation_uri": null,
            "atm_transfer_reference": {
            	"company_id": null,
                "transaction_id": null
        	},
            "available_actions": [],
        	"card_id": null,
        	"collector": {
            	"id": 169648308
        	},
        	"coupon_amount": 0,
        	"coupon_id": null,
        	"currency_id": "BRL",
	        "date_created": "2014-10-26T22:50:10.000-04:00",
            "date_last_modified": "2014-10-26T22:50:21.000-04:00",
        	"id": 885920410,
        	"installments": 3,
        	"issuer_id": "25",
        	"operation_type": "regular_payment",
        	"order_id": 893431118,
        	"overpaid_amount": 0,
        	"payer_id": 160903317,
            "payment_method_id": "visa",
        	"payment_type": "credit_card",
        	"reason": "Item De Testeo, Por Favor No Ofertar --kc:off",
        	"shipping_cost": 0,
        	"site_id": "MLB",
        	"status": "approved",
        	"status_code": null,
        	"status_detail": "accredited",
            "total_paid_amount": 315.62,
            "transaction_amount": 295
    	}
	],
	"seller": {
    	"alternative_phone": {
        	"area_code": null,
        	"extension": null,
        	"number": ""
    	},
    	"email": "test_user_70385259@testuser.com",
    	"first_name": "Test",
  	  "id": 169648308,
    	"last_name": "Test",
    	"nickname": "TETE6072468",
    	"phone": {
        	"area_code": "01",
        	"extension": null,
        	"number": "1111-1111"
    	}
	},
	"shipping": {
    	"status": "to_be_agreed"
	},
	"status": "paid",
	"status_detail": null,
	"tags": [
    	"not_delivered",
    	"paid"
	],
	"total_amount": 591,
    "total_amount_with_shipping": 591
}

How to get information about a payment?

To get information about a buyer’s payment, using the token go to “payments” resource.

Example:

https://api.mercadolibre.com/payments?access_token=

How to get information about a payment from the seller?

To get information about a payment from the seller’s role, go to payment_id es “collections” resource.

Example:

https://api.mercadolibre.com/collections/{collection_id}?access_token=

Advanced

Order Notes

A note is an annotation sellers can add to orders. Notes can have up to 300 characters each and, once you post a note, you can either modify or delete it.

How to add a note to an order?

curl -X POST -H "Content-Type: application/json" -d '{  	
   	"note": "test",
}' https://api.mercadolibre.com/orders/{order_Id}/notes?access_token=$ACCESS_TOKEN

See Order Notes

curl -X GET https://api.mercadolibre.com/orders/{order_Id}/notes?access_token=$ACCESS_TOKEN

How to modify a note?

curl -X PUT -H "Content-Type: application/json" -d '{
   	"note": "test2",
}' https://api.mercadolibre.com/orders/{order_Id}/notes/{note_Id}?access_token=$ACCESS_TOKEN

Delete Notes

curl -X DELETE https://api.mercadolibre.com/orders/{order_Id}/notes/{note_Id}?access_token=$ACCESS_TOKEN

Block Bids

Even though we have a fraud prevention feature and flows to keep buyers and sellers safe, sometimes you may find users who, for some reason, bid on your items. These cases can be sent to your blacklist to prevent them from bidding.

How do I block bids from a specific user?

Make a POST with the cust_id of the user you want to block on the JSON and yours in the url, like in the following example:

curl -X POST -H "Content-Type: application/json" -d
{ user_id: {cust_id} }
https://api.mercadolibre.com/users/{cust_Id}/order_blacklist?access_token=$ACCESS_TOKEN

Check your blacklist

If you want to know which users are on your blacklist, make a GET to the API with your cust_id in the url:

curl -X GET https://api.mercadolibre.com/users/{cust_id}/order_blacklist?access_token=$ACCESS_TOKEN

Remove a user from your blacklist

If you don’t want to block a user from making bids anymore, you can remove him/her from your blacklist by making a DELETE to the API with your cust_id and the blocked user’s cust_id.

curl -X DELETE https://api.mercadolibre.com/users/{your_cust_id}/order_blacklist/{cust_id}

Error Code Reference

Error 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.

Can not identify the user. 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.



Next topic:
Messaging API.

Please rate this