Manage orders

Receive notifications

Some events happen on Global Selling’s side and notifications are the only way to become aware of them. Receiving notifications enables you to have a real-time feed of the changes that occur on the different resources of our API. Learn more about notifications.

Order status

Order statuses are the following:
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.
cancelled For some reason, the order was not fulfilled.*
invalid The order was invalidated as it came from a malicious buyer.

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.

To consume this resource, make a call with GET method as shown in the following curl:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/orders/search

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/orders/search

Cart order response:

{
            "id": 2000000580342535, -> Don't use it. Use the orders node id.
            "buyer": {
                "id": 116038996
            },
            "config": {
                "items": [
                    {
                        "id": "MLM759344664"
                    }
                ]
            },
            "orders": [
                {
                    "id": 2497671750, -> This is the order id you have to use.
                    "items": null,
                    "feedback": {
                        "purchase": null,
                        "sale": null
                    },
                    "payments": [
                        {
                            "id": 7032122688
                        }
                    ],
                    "mediations": [],
                    "seller": {
                        "id": 514048142
                    }
                }
            ],
            "shipment": {
                "id": 28504764933,
                "payments": []
            }
        }

Individual order response:

{
            "id": 2483140131,
            "buyer": {
                "id": 441782523
            },
            "config": {
                "items": [
                    {
                        "id": "MLM781272686"
                    }
                ]
            },
            "orders": [
                {
                    "id": 2483140131, -> this is the order id.
                    "items": null,
                    "feedback": {
                        "purchase": null,
                        "sale": null
                    },
                    "payments": [
                        {
                            "id": 6903805442
                        }
                    ],
                    "mediations": [
                        {
                            "id": 5022947125
                        }
                    ],
                    "seller": {
                        "id": 523132944
                    }
                }
            ],
            "shipment": {
                "id": 30041416576,
                "payments": []
            }
        }

Parameters

sort: shows field you can use to sort results.
order: shows order direction you need to organize results with.
limit: the limit of results requested, it has a maximum of 1000.
offset: using the offset attribute, you can move the lower limit of the result block.

Search orders with filters

Search orders using limit filter resource allows to restrict results. You should make a call using GET method like this:

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET  https://api.mercadolibre.com/marketplace/orders/search?buyer=$BUYER_ID&limit=$LIMIT

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/orders/search?buyer=441782523&limit=50

Response:

{
   "query":"",
   "results":[
      {
         "id":2194210960,
         "buyer":{
            "id":441782523
         },
         "config":{
            "items":[
               {
                  "id":"MLM733232983"
               }
            ]
         },
         "orders":[
            {
               "id":2194210960,
               "items":null,
               "feedback":{
                  "purchase":null,
                  "sale":null
               },
               "payments":[
                  {
                     "id":5384783409
                  }
               ],
               "mediations":[
                  {
                     "id":1041550651
                  }
               ]
            }
         ],
         "shipment":{
            "id":28140042692,
            "payments":[

            ]
         }
      },
      {
         "id":2194336280,
         "buyer":{
            "id":441782523
         },
         "config":{
            "items":[
               {
                  "id":"MLM733232983"
               }
            ]
         },
         "orders":[
            {
               "id":2194336280,
               "items":null,
               "feedback":{
                  "purchase":null,
                  "sale":null
               },
               "payments":[
                  {
                     "id":5384748271
                  }
               ],
               "mediations":[
                  {
                     "id":5007508763
                  }
               ]
            }
         ],
         "shipment":{
            "id":28139907607,
            "payments":[

            ]
         }
      }
   ],
   "sort":{
      "id":"date_asc",
      "name":"Date ascending"
   },
   "available_sorts":[
      {
         "id":"date_desc",
         "name":"Date descending"
      }
   ],
   "filters":[],
   "paging":{
      "total":2,
      "limit":50,
   }
}

Parameters

buyer: to search orders by certain buyer.

seller.id: to search orders by certain seller.

order.status: to search orders by certain status (paid, cancelled, payment_required, paid).

site: to search orders of country shown in site (MLM, MLB, MLC).

limit: to reduce page size changing number of results to show in each page. If not stated, 50 results will be brought -maximum allowed value.

offset: using the offset attribute, you can move the lower limit of the result block.

date_created.from: to search from a certain order creation date.

date_created.to: to search for orders created up to a certain date.

last_updated.from: to search from a certain order update date.

last_updated.to: to search for orders updated up to a certain date.

date_closed.from: to search from a certain closing date.

date_closed.to: to search for orders closed until a certain date.

mediations.stage: it can be some status separated by ','

Available date formats

• yyyy-MM (eg 1997-07)
• yyyy-MM-dd (eg 1997-07-16)
• yyyy-MM-ddThh (eg 1997-07-16T19)
• yyyy-MM-ddThh:mm (eg 1997-07-16T19:20)
• yyyy-MM-ddThh:mm:ss (eg 1997-07-16T19:20:30)
• yyyy-MM-ddThh:mm:ss.ms (eg 1997-07-16T19:20:30.45)
• yyyy-MM-ddThh:mm:ss.ms-TZD (eg 1997-07-16T19:20:30.45-01:00)



yyyy = four-digit year
MM = two-digit month (01=January, etc.)
dd = two-digit day of month (01 through 31)
hh = two digits of hour (00 through 23) (am/pm NOT allowed)
mm = two digits of minute (00 through 59)
ss = two digits of second (00 through 59)
ms = one or more digits representing a decimal fraction of a second
TZD = time zone designator (hh:mm)
T = Time separator between date and time, must be a T letter

Available sorts

Search orders can receive parameters with which you can sort the search results by dates. The available sorts parameters are:

date_asc: date ascending
date_desc: date descending
updated_asc: last updated ascending
updated_desc: last updated descending
closed_asc: date close ascending
closed_desc: date close descending

Errors

Get an order

For implementation, make a request with GET method as shown below:

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/orders/$ORDER_ID

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/orders/2000003508419013

Response:

{
    "id": 2000003508419013,
    "date_created": "2020-01-31T18:03:35.000-04:00",
    "date_closed": "2020-01-31T18:03:36.000-04:00",
    "last_updated": "2020-01-31T18:03:36.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,
    "paid_amount": 15.1,
    "coupon": {
        "id": null,
        "amount": 0
    },
    "expiration_date": "2020-05-10T18:03:36.000-04:00",
    "order_items": [
        {
            "item": {
                "id": "MLM754639529",
                "title": "Elemento De Prueba - Para Pruebas De Carga",
                "category_id": "MLM71792",
                "variation_id": null,
                "seller_custom_field": null,
                "variation_attributes": [],
                "condition": "new",
                "seller_sku": null,
                "parent_item_id": "CBT910504819"
            },
            "quantity": 1,
            "unit_price": 15.1,
            "full_unit_price": 15.1,
            "currency_id": "USD",
            "manufacturing_days": null,
            "sale_fee": 2.64,
            "base_exchange_rate": 19.25
        }
    ],
    "currency_id": "USD",
    "payments": [
        {
            "id": 5855860136,
            "order_id": 2000003508419013,
            "payer_id": 441782523,
            "collector": {
                "id": 481240836
            },
            "card_id": 8738685222,
            "site_id": "MLM",
            "reason": "Elemento De Prueba - Para Pruebas De Carga",
            "payment_method_id": "amex",
            "currency_id": "USD",
            "installments": 1,
            "issuer_id": "157",
            "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": 15.1,
            "taxes_amount": 0,
            "shipping_cost": 0,
            "coupon_amount": 0,
            "overpaid_amount": 0,
            "total_paid_amount": 15.1,
            "installment_amount": 15.1,
            "deferred_period": null,
            "date_approved": "2020-01-31T18:03:36.000-04:00",
            "authorization_code": "1234567",
            "transaction_order_id": null,
            "date_created": "2020-01-31T18:03:36.000-04:00",
            "date_last_modified": "2020-01-31T18:03:36.000-04:00"
        }
    ],
    "shipping": {
        "id": 28237306862
    },
    "status": "paid",
    "status_detail": {
        "code": "",
        "description": null
    },
    "buyer": {
        "id": 441782523,
        "nickname": "TESTY0DT2NRL",
        "last_name": "Test",
        "first_name": "Test",
    },
    "seller": {
        "id": 481240836,
    },
    "taxes": {
        "amount": 0,
        "currency_id": "USD"
    }
    "context": {
       "channel": "marketplace",
       "site": "MLM",
       "flows": [
           "cbt"
       ],
       "application": "purchases-api"
   }
}

We remove the data of buyer's billing info from the order. Please, check this data by doing a GET to /orders/order_id/billing_info.

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.

currency_id: you need to define a currency. You need to use USD. This one is also a mandatory attribute.

status_detail: status detail.

code: status code.

description: status description.

buyer: buyer's information

seller: 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.

tags: amount with the sum of taxes to be paid from the order.

Parameters

id: unique order identifier.

Errors

As soon as you receive an orders notification, with the order ID you get the information making a request to the /marketplace/orders resource (get an order). Then, with the shipping ID you can identify the logistics (logistic_type and mode) by consulting the /marketplace/shipments resource (get shippment details). With this information, you will know what steps you should take next depending on each shipping method.

*The error 404 can occur when trying to query a pack_id with the orders resource. Please review how to Manage Cart Orders

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.

Invoice

Get the "proforma" invoice to be used for customs declarations.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/orders/$ORDER_ID/invoice

Example:

Add product information

Due to regulations in the Colombian market, it will be mandatory to include the IMEI number (IMEI stands for International Mobile Equipment Identity. It is a unique 15-digit number assigned to every mobile phone and smartphone.) on the label when buyers from this market purchase mobile phones. For this purpose, items associated with the category ID MCO1055 are considered cell phone purchases. To comply with this requirement, we have made available a writing resource on the label that allows for the inclusion of the IMEI number of the mobile phone being shipped in the package. For implementation, make a request with POST method as shown below:

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
   "name": "IMEI",
 "value": "1234567890ABCDE"
 }'
https://api.mercadolibre.com/marketplace/orders/$ORDER_ID/attributes

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
   "name": "IMEI",
 "value": "1H24HD121H24HD1"
 }'
https://api.mercadolibre.com/marketplace/orders/2000003508419223/attributes

Response: Status Code 201

{
   "status": "success"
 }

Errors