Manage orders

An order is a request made by a customer on a listed item that intends to buy under a series of conditions to be selected in the online checkout flow. These conditions are detailed in the order that will be replicated for buyer and seller accounts. You will find information about the product to fill out there. The Global Selling orders correspond to each local marketplace (México, Brasil and Chile) and sellers manage these orders in a unified way.
Next, we detail the order management flow.

Contents

→Receive notifications
→Order status
→Search orders
   ↳Search orders with filters
→Get an order detail
→Fraud alerts (stop shipping)
→Invoice


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.

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

Search orders

The search order resource will help you find the order that belongs to a user. In short, you can see the flow to follow to search orders by Global Selling buyer. To consume this resource, make a call with GET method as shown in the following curl:

Note:
This request has a limit 100 request per minute.

Request:

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": []
            }
        }
Note:
Use the order ID´s from the orders node.

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

logisitic.type: to search orders by logistics showing, for example, remote, fulfillment.

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

HTTP Code Error Message
403 forbidden Invalid caller.id
403 forbidden Can not identify the user
404 not_found Resource not found
500 internal_server_error Oops! Something went wrong...
401 not_found invalid_token
400 bad_request {"message":"Malformed access_token: TOKEN_NOT_VALID","error":"bad_request","status":400,"cause":[]}
400 bad_request Param not valid

Get an order detail

Important:
As of February 14, 2022, order IDs will be 16 digits (long data type).

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,
        "nickname": "TESTUSA1TESTUSERUSA1",
        "last_name": "TESTUSERUSA1",
        "first_name": "Test Usa 1"
    },
    "taxes": {
        "amount": 0,
        "currency_id": "USD"
    }
}

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

HTTP Code Error Message
403 forbidden Invalid caller.id
403 forbidden Can not identify the user.
404 not_found Resource not found.
500 internal_server_error Oops! Something went wrong...
401 not_found invalid_token
400 bad_request {"message":"Malformed access_token: TOKEN_NOT_VALID","error":"bad_request","status":400,"cause":[]}
400 bad_request Param not valid

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 about depending on each shipping method.


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.


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

Example:



Next: Shipments.