Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 24/10/2023

Customer data access

Important:
- To access these APIs both the vendor and the integrator need to meet certain requirements, they must control the errors that the resource may give as a response for not having the required requirements.
- In order to make use of the resource, you must complete the following form, in order to access the certification process and meet the requirements.

Mercado Shops sellers need to have access to their customers' data in order to use them in marketing campaigns or to visualize in a granular way the sales they have over a period of time.
Mercado Shops sellers need to have access to their customers' data in order to use them in marketing campaigns or to visualize in a granular way the sales they have over a period of time.


Note:
If you want to learn more about how to work with the information available from the salesperson's sales, you can find more information in post-sales experience..


Consult by date range

Important:
To make queries with dates, the query does not consider minutes or seconds, only ranges of hours.

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?order_created_from=$DATE_FROM&order_created_to=$DATE_TO

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?order_created_from=2021-01-18T00:00:00.000-00:00&order_created_to=2022-01-18T00:00:00.000-00:00

Response:

'{
    "results": [
        {
            "id": 4749149808,
            "date_created": "2021-07-29T11:32:23.000+00:00",
            "paid_amount": 1150.0,
            "currency_id": "ARS",
            "buyer": {
                "id": 798779895,
                "person": {
                    "birthdate": "1981-06-18",
                    "first_name": "Buyer",
                    "gender": "F",
                    "last_name": "Blackburn 798779895"
                },
                "contact": {
                    "email": "sheree.blackburn+798779895@example.co.uk",
                    "phone": "54 1199351139 ext. 261"
                },
                "ms_seller_promotions": true
            },
            "order_items": [
                {
                    "item": {
                        "title": "Item De Testeo, Por Favor No Ofertar --kc:off"
                    }
                },
                {
                    "item": {
                        "title": "Item De Testeo 2, Por Favor No Ofertar --kc:off"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 4697463433,
            "date_created": "2021-07-07T15:41:55.000+00:00",
            "paid_amount": 1494.99,
            "currency_id": "ARS",
            "buyer": {
                "id": 780777832,
                "person": null,
                "contact": {
                    "email": "sheree.blackburn+780777832@example.co.uk",
                    "phone": "54 1199351139"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Item De Testeo, Por Favor No Ofertar --kc:off"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 4697450495,
            "date_created": "2021-07-07T15:38:08.000+00:00",
            "paid_amount": 1500.0,
            "currency_id": "ARS",
            "buyer": {
                "id": 780777832,
                "person": {
                    "birthdate": "1981-06-18",
                    "first_name": "Buyer",
                    "gender": "F",
                    "last_name": "Blackburn 780777832"
                },
                "contact": {
                    "email": "sheree.blackburn+780777832@example.co.uk",
                    "phone": "541199351139"
                },
                "ms_seller_promotions": true
            },
            "order_items": [
                {
                    "item": {
                        "title": "Sticker Tarjetas"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 4647686563,
            "date_created": "2021-06-16T17:26:41.000+00:00",
            "paid_amount": 2004.99,
            "currency_id": "ARS",
            "buyer": {
                "id": 656454498,
                "person": {
                    "birthdate": "1981-01-12",
                    "first_name": "Mark",
                    "gender": "M",
                    "last_name": "Blackburn 656454498"
                },
                "contact": {
                    "email": "mark.blackburn+656454498@example.co.uk",
                    "phone": null
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Billetera Ideal Para Gente Como Vos!"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        }
    ],
    "paging": {
        "total": 4,
        "limit": 15,
        "scroll_id": "YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1vcmlnaW5hbC1vcmRlcnMtMDM=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEs1djliWDRCdW1sSjF0ZENGS3l0AAAAAHPJOh0WRUlRNGJVc3FTUWk5ZUtLN0NEM2NDQQ=="
    }
}'

Consult by scroll id

Having already performed the first query by date range and obtained the corresponding scroll_id, you can query with the value received. Continue with the following resources:

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?scroll_id=$SCROLL_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?scroll_id=YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1vcmlnaW5hbC1vcmRlcnMtMDM=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEs1djliWDRCdW1sSjF0ZENGS3l0AAAAAHPJOh0WRUlRNGJVc3FTUWk5ZUtLN0NEM2NDQQ==

Response with the list of buyers and their information

'{
    "results": [
        {
            "id": 4749149808,
            "date_created": "2021-07-29T11:32:23.000+00:00",
            "paid_amount": 1150.0,
            "currency_id": "ARS",
            "buyer": {
                "id": 798779895,
                "person": {
                    "birthdate": "1981-06-18",
                    "first_name": "Buyer",
                    "gender": "F",
                    "last_name": "Blackburn 798779895"
                },
                "contact": {
                    "email": "sheree.blackburn+798779895@example.co.uk",
                    "phone": "54 1199351139 ext. 261"
                },
                "ms_seller_promotions": true
            },
            "order_items": [
                {
                    "item": {
                        "title": "Item De Testeo, Por Favor No Ofertar --kc:off"
                    }
                },
                {
                    "item": {
                        "title": "Item De Testeo 2, Por Favor No Ofertar --kc:off"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 4697463433,
            "date_created": "2021-07-07T15:41:55.000+00:00",
            "paid_amount": 1494.99,
            "currency_id": "ARS",
            "buyer": {
                "id": 780777832,
                "person": null,
                "contact": {
                    "email": "sheree.blackburn+780777832@example.co.uk",
                    "phone": "54 1199351139"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Item De Testeo, Por Favor No Ofertar --kc:off"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 4697450495,
            "date_created": "2021-07-07T15:38:08.000+00:00",
            "paid_amount": 1500.0,
            "currency_id": "ARS",
            "buyer": {
                "id": 780777832,
                "person": {
                    "birthdate": "1981-06-18",
                    "first_name": "Buyer",
                    "gender": "F",
                    "last_name": "Blackburn 780777832"
                },
                "contact": {
                    "email": "sheree.blackburn+780777832@example.co.uk",
                    "phone": "541199351139"
                },
                "ms_seller_promotions": true
            },
            "order_items": [
                {
                    "item": {
                        "title": "Sticker Tarjetas"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 4647686563,
            "date_created": "2021-06-16T17:26:41.000+00:00",
            "paid_amount": 2004.99,
            "currency_id": "ARS",
            "buyer": {
                "id": 656454498,
                "person": {
                    "birthdate": "1981-01-12",
                    "first_name": "Mark",
                    "gender": "M",
                    "last_name": "Blackburn 656454498"
                },
                "contact": {
                    "email": "mark.blackburn+656454498@example.co.uk",
                    "phone": null
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Billetera Ideal Para Gente Como Vos!"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        }
    ],
    "paging": {
        "total": 4,
        "limit": 15,
        "scroll_id": "YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1vcmlnaW5hbC1vcmRlcnMtMDM=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEs1djliWDRCdW1sSjF0ZENGS3l0AAAAAHPJOh0WRUlRNGJVc3FTUWk5ZUtLN0NEM2NDQQ=="
    }
}'

Query by buyer_id

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?buyer_id=$BUYER_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?buyer_id=1080426219

Answer with the orders registered by the buyer and his information.

{
    "results": [
        {
            "id": 2000005004071824,
            "date_created": "2023-01-26T21:27:24.000+00:00",
            "buyer": {
                "id": 1080426219,
                "person": {
                    "birthdate": "1987-05-26",
                    "first_name": "Faulkner",
                    "gender": "M",
                    "last_name": "Hoover"
                },
                "contact": {
                    "phone": "542661180352832",
                    "email": "faulkner.hoover@example.net"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
                        "id": "MLA897945718"
                    }
                }
            ],
            "paid_amount": 1150.0,
            "currency_id": "ARS",
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 2000005003466456,
            "date_created": "2023-01-26T19:44:18.000+00:00",
            "buyer": {
                "id": 1080426219,
                "person": {
                    "birthdate": "1987-05-26",
                    "first_name": "Faulkner",
                    "gender": "M",
                    "last_name": "Hoover"
                },
                "contact": {
                    "phone": "542661180352832",
                    "email": "faulkner.hoover@example.net"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Peluche De Stitch",
                        "id": "MLA932413098"
                    }
                }
            ],
            "paid_amount": 1974.99,
            "currency_id": "ARS",
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 2000005003174726,
            "date_created": "2023-01-26T18:58:33.000+00:00",
            "buyer": {
                "id": 1080426219,
                "person": {
                    "birthdate": "1987-05-26",
                    "first_name": "Faulkner",
                    "gender": "M",
                    "last_name": "Hoover"
                },
                "contact": {
                    "phone": "542661180352832",
                    "email": "faulkner.hoover@example.net"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
                        "id": "MLA897945718"
                    }
                }
            ],
            "paid_amount": 1150.0,
            "currency_id": "ARS",
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 2000005002534814,
            "date_created": "2023-01-26T17:21:16.000+00:00",
            "buyer": {
                "id": 1080426219,
                "person": {
                    "birthdate": "1987-05-26",
                    "first_name": "Faulkner",
                    "gender": "M",
                    "last_name": "Hoover"
                },
                "contact": {
                    "phone": "542661180352832",
                    "email": "faulkner.hoover@example.net"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Pilas",
                        "id": "MLA930546840"
                    }
                }
            ],
            "paid_amount": 3400.0,
            "currency_id": "ARS",
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 5289783151,
            "date_created": "2022-02-25T14:11:04.000+00:00",
            "buyer": {
                "id": 1080426219,
                "person": {
                    "birthdate": "1987-05-26",
                    "first_name": "Faulkner",
                    "gender": "M",
                    "last_name": "Hoover"
                },
                "contact": {
                    "phone": "542661180352832",
                    "email": "faulkner.hoover@example.net"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Sticker Tarjetas",
                        "id": "MLA897947944"
                    }
                }
            ],
            "paid_amount": 1500.0,
            "currency_id": "ARS",
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        }
    ],
    "paging": {
        "total": 5,
        "limit": 5,
        "scroll_id": "YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1taXJyb3ItMDY=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEFtWDVQSVlCX0pCUHQ4ckpfYXBCAAAAABfg_NMWbE5JZEVULVRUbGl1Mk9jYW1pZ0Y1UQ=="
    }
}

Query by order_id

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?order_id=$ORDER_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?order_id=2000005003466456

Answer with the requested order and its information

{
    "results": [
        {
            "id": 2000005003466456,
            "date_created": "2023-01-26T19:44:18.000+00:00",
            "buyer": {
                "id": 1080426219,
                "person": {
                    "birthdate": "1987-05-26",
                    "first_name": "Faulkner",
                    "gender": "M",
                    "last_name": "Hoover"
                },
                "contact": {
                    "phone": "542661180352832",
                    "email": "faulkner.hoover@example.net"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Peluche De Stitch",
                        "id": "MLA932413098"
                    }
                }
            ],
            "paid_amount": 1974.99,
            "currency_id": "ARS",
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        }
    ],
    "paging": {
        "total": 1,
        "limit": 1,
        "scroll_id": "YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1vcmlnaW5hbC1vcmRlcnMtMDM=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFGxCVDBQSVlCcXNsaC1IVHFaal9wAAAAAMNKjsAWQVlMWk9VLTRUUENHelJRWUg0dHRWdw=="
    }
}

Glossary

Request parameters

Fields Field description Possible values for the field and its description
order_created_from Start and end date of the search. Compare against the creation date of the orders. Must be in ISO-8601 format. 2021-01-18T00:00:00.000-00:00
order_created_to Start and end date of the search. Compare against the creation date of the orders. Must be in ISO-8601 format. 2022-01-18T00:00:00.000-00:00
scroll_id Used to continue paging the search. YXBpY29yZS1vcmlnaW5hb
C1vcmRlcnM=:ZHMtYXBpY
29yZS1vcmlnaW5hbC1vcm
RlcnMtMDM=:FGluY2x1ZG
VfY29udGV4dF91dWlkDXF
1ZXJ5QW5kRmV0Y2gBFEs1
djliWDRCdW1sSjF0ZENGS
3l0AAAAAHPJOh0WRUlRNG
JVc3FTUWk5ZUtLN0NEM2N
DQQ==
buyer_id It is used to search for information filtering by buyer id. 1080426219
order_id Used to filter by a specific order. 2000005003466456

Response parameters

Fields Field description Possible values for the field and its description
results List of orders. [ ] , [order], [order, order, …]
paging Search pagination information. Paging [ total, limit, scroll_id]

Order

Fields Field description Possible values for the field and its description
id Order id. order_id.
date_created Date and time of order creation. Date and time expressed according to ISO 8601 Example: 2021-06-16T17:26:41.000+00:00
paid_amount Amount paid by the buyer on the order. value.
currency_id Type of currency in which payment was made. Value according to the ISO 4217 of the currency, example: COP, MXN, ARS, CLP, BRL.
buyer Order buyer. buyer.
order_items List of items purchased. [ ], [orderItem], [order_Item, orderItem, …]
coupon Coupon information used in the order (if applicable). coupon

Buyer

Fields Field description Possible values for the field and its description
id Id of the buyer. Id of the buyer.
person Buyer's information, may be null. person.
contact Buyer's contact information. contact.
ms_seller_promotions Acceptance by the purchaser to receive promotional information through their contact information. true: buyer agrees to receive promotional information.
false: the buyer does no agree to receive promotional information.

Person

Fields Field description Possible values for the field and its description
birthday Buyer's birthday. May be a no-show. Ex. 1999-01-20 format YYYY-MM-DD
first_name Name of buyer.
last_name Buyer's last name.
gender Gender registered for the buyer according to his/her identity document. May not be presented. F: female.
M: male.

Contact

Fields Field description Possible values for the field and its description
email Buyer's email.
phone Buyer's phone.

Coupon

Fields Field description Possible values for the field and its description
id ID of the buyer. If it arrives null, it means that no discount coupon was applied to the purchase.
amount Discount applied to the purchase with the coupon.

OrderItem

Fields Field description Possible values for the field and its description
Item Item information. Item.

Ítem

Fields Field description Possible values for the field and its description
Title Title of the publication of the item.
Id Item ID.

Paging

Fields Field description Possible values for the field and its description
total Total orders resulting from the search.
limit Maximum number of orders submitted per page.
scroll_id Scroll id of the search. To continue the search you must send this value as a parameter in the next query, always use the last one generated.

Errores

Status_Code Código de error Mensagem de erro Descrição Possível solução
400 bad request The date range must be sent. The integrator must send the date range to be able to make the request.
401 unauthorized Seller has pending to ask their identity validation. The seller did not validate your identity. The seller to which you are associating must access the Mshops panel, enter the customer section and complete the validation flow. More information on our devsite.
401 unauthorized Signature not found by user_id and checkpoint_id Seller did not sign the terms and conditions. The seller to which you are associating must access the Mshops panel, enter the customer section and complete the validation flow. More information on our devsite.
401 unauthorized Client.id not allowed to continue operation The client_id does not have permissions to access the vendor's information. The functionality is exclusive to selected partners.
401 unauthorized invalid_token Verify the access_token.
403 forbidden ACCESS_TOKEN_NOT_GRANTED You do not have permissions to perform the query. Verify that you have permission through the integrator to query this API.
404 not_found There is no more info associated with this scroll_id The seller has no more sales associated with the given scroll_id. That is to say that the pagination is already finished.
429 too_many_requests Over quota Too many requests were made in a short period of time.
500 internal_server_error It is due to an unexpected error in any step of the flow. Contact us to determine the cause.