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


Request:

curl -X GET https://api.mercadolibre.com/marketplace/orders/search?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/marketplace/orders/search?access_token=$ACCESS_TOKEN

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

access_token: token you need to create with credentials provided and application generated by seller or integrator.

sort: shows field you can use to sort results.

order: shows order direction you need to organize results with.

scroll_id: allows for result paging. To do this, you should send this parameter from the second iteration.


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 -X GET https://api.mercadolibre.com/marketplace/orders/search?buyer=$BUYER_ID&limit=$LIMIT&access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/marketplace/orders/search?access_token=$ACCESS_TOKEN

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,
      "scroll_id":"YXNzb3J0ZWQtbWVkaXVtLXpldGE=:ZHMtYXNzb3J0ZWQtbWVkaXVtLXpldGEtMDE=:DXF1ZXJ5QW5kRmV0Y2gBAAAAAHwHLPoWNGFZYkhsa1RRU2k2VFpnd1kzZnI3dw=="
   }
}

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.

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.


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

This resource will help you get details about an order in production as shown in this flow:

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


Request:

curl -X GET https://api.mercadolibre.com/marketplace/orders/$ORDER_ID?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/marketplace/orders/2302846452?access_token=$ACCESS_TOKEN

Response:

{
    "id": 2302846452,
    "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": 2302846452,
            "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",
        "billing_info": {
            "doc_type": null,
            "doc_number": null
        }
    },
    "seller": {
        "id": 481240836,
        "nickname": "TESTUSA1TESTUSERUSA1",
        "last_name": "TESTUSERUSA1",
        "first_name": "Test Usa 1"
    },
    "taxes": {
        "amount": 0,
        "currency_id": "USD"
    }
}

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.

access_token: access key to private resources.


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.


Invoice

The resource to obtain an invoice is the following.


curl -X GET https://api.mercadolibre.com/marketplace/orders/$ORDER_ID/invoice?access_token=$ACCESS_TOKEN

Example:



Next: Shipments.