
If your company sells on Mercado Libre, you may know this morning routine. Someone opens the seller account, downloads the previous day’s sales and types them into the ERP, order by order. Later, someone else changes the stock on the listings, when they remember to. When an item runs out in the warehouse it stays on sale on Mercado Libre, a buyer pays for it, and the sale has to be cancelled. At the end of the month, the accounts team looks at the Mercado Pago account, sees money that came in, and tries to work out which orders it belongs to.
Every sale on Mercado Libre leaves three things to do in your systems: an order to enter, stock to update and a payment to record. They involve two platforms. Mercado Libre is the marketplace, with the listings, the orders and the shipments. Mercado Pago is where the money from those sales arrives, waits and leaves for your bank. Both publish developer documentation, and that documentation shapes the design more than it first appears.
This piece follows a sale from the moment it happens to the moment its money reaches the bank. For each step it sets out what the two platforms offer, as their developer documentation states it, the rules a connection has to keep, and the decisions only your company can make. Then an example from start to finish, and the first steps you can take this week.
Two platforms, three flows
Before any detail, the shape. Between Mercado Libre, Mercado Pago and your ERP there are three flows, and they do not all run the same way.
Orders come in: a sale on Mercado Libre becomes an order in the ERP, with its lines, its buyer details and its shipment. Stock goes out: the quantities in your warehouse are sent to the listings, so that no one sells what you no longer have. Payments come in: each Mercado Pago payment is recorded against its order.
There is one exception to the second flow, and it matters. If you use Mercado Libre’s own fulfilment service, Full, Mercado Libre stores those units in its warehouses and prepares those orders. For the units in Full, Mercado Libre manages the stock count: nothing is sent to it from your side, and your ERP can only read it. A listing can have units in Full and also ship from your own warehouse at the same time; that part, where the country allows it to be sent separately, takes your warehouse’s figure.
Before the first order: the app, the authorisation, the countries and the tests
A connection does not start with code. It starts with four things to know on the platforms’ side.
The app, and who authorises it
To read and write data in your account, the connection has to be an application created in Mercado Libre’s application manager, and your account authorises it through OAuth, the standard authorisation flow: someone signs in on Mercado Libre and approves the application, which receives an authorisation code and exchanges it for an access token. The documentation is precise about who: the user who signs in must be an administrator of the account, so that the token has enough permissions; if the user is an operator or collaborator, the authorisation is not valid. The details of a payment are read from Mercado Pago’s own API, so the Mercado Pago account authorises the connection too.
Tokens that expire, and authorisations that end
The access token lasts a few hours. The documentation’s text says six, while the sample response it shows gives 10,800 seconds, three hours: the connection reads the lifetime from each response, instead of trusting a fixed figure. To get a new access token it uses a refresh token, and the refresh token can be used only once. Each refresh returns a new one, only the latest one works, and it lasts six months.
The documentation also lists events that invalidate an access token early: a change of the user’s password, a new application secret, the user revoking the application, four months without calls to the API. A revocation also deletes the refresh token, whether the user makes it, the integrator does, or Mercado Libre does internally, for instance after a password change, unlinked devices or suspected fraud. Then the connection can no longer read or write the account until someone authorises it again.
That makes the authorisation a part of the system to look after, like a certificate. Who authorised the application, with which administrator user, and what happens when that person leaves or changes the password: these are questions to answer before the first order, not after a Monday when nothing came in. A connection that loses its authorisation should say so at once, to a person, rather than fail quietly.
One site per country
On Mercado Libre each country is a separate site, with its own identifier: MLA for Argentina, MLB for Brazil, MLM for Mexico, MLC for Chile and MCO for Colombia, among others. Each order says on which site it was placed, and its currency.
If you sell in two countries you have two sites, with their own listings and their own currencies, and sometimes a separate company in each country, with its own books. The connection has to know which company of your ERP each account’s orders belong to, and in which currency they are posted. That is a decision for the business, written down before the first order arrives.
No sandbox
Mercado Libre’s documentation is blunt about testing: there is no test environment or sandbox. What it offers are test users, up to ten, which work directly in production and can only trade with the listings of other test users; a test user with no activity for sixty days is deleted. A test has to be designed with that in mind, as described further on, before the first real sale.
How a sale reaches the ERP
A sale can reach the connection in two ways: the platform says it happened, or the connection asks. A good connection uses both.
The notice
In the application you choose the topics you want to hear about. The topic of orders is orders_v2, which reports the creation of confirmed sales and their changes. There are others, for listings, shipments, payments and stock locations, and the claims of a sale come under the post-purchase topic. The notice arrives as a request to the web address the application gave, and it carries only which resource changed. To know what changed, the connection then reads that resource.
The documentation adds a reason to always read it again: changes do not come only from your connection. Someone working in the seller’s panel, or another application with access to the account, can change an order or a listing too, and the notice is the same.
Five hundred milliseconds
The documentation sets how that web address must behave. It has to confirm every notice with an HTTP 200 code; otherwise the notice counts as not delivered and is retried for an hour. After that hour Mercado Libre stops retrying it and treats it as lost; lost notices can still be listed for two days through missed_feeds. And it has to confirm within 500 milliseconds: otherwise Mercado Libre may switch off the application’s notification topics, the notices of that period are not kept for later, and the application has to subscribe again.
The design that follows is a queue. The web address writes the notice down and answers at once, and only afterwards does the connection read the order. Reading an order, matching it and writing it into the ERP can take longer than 500 milliseconds, as the documentation itself recommends: none of that work should happen while Mercado Libre waits for its answer.
The safety net
Notices are the fast road, not the only one. At regular intervals the connection also searches the seller’s recent orders, with the date filters the search offers, in case one never arrived as a notice, or arrived while the topics were switched off.
That has a consequence: the same order can reach the connection twice, once by notice and once by search, or twice by notice when the platform retries. The connection must recognise it. The simple way is to use the platform’s order number as the key: if an order with that number already exists in the ERP, it is updated, never created again.
The search has two limits worth knowing. Mercado Libre keeps the orders created in the last twelve months, so the history has to live in the ERP. And when the search is run as the seller, it leaves out cancelled orders, so a cancellation does not come back through it: it comes through the notice of the order, or by re-reading an order the ERP already has.
What an order carries
An order on Mercado Libre is not a copy of a sales order in your ERP. Some of what your ERP expects is in it, some is elsewhere, and some is not there at all.
The lines, and your item code
For each line, an order carries the listing, the variation if there is one, the quantity, the unit price and the currency, and the seller’s code of that listing. That code is where your item code belongs. The documentation is specific about it: the right place to keep the seller’s code is the listing’s SELLER_SKU attribute; the other field that looks like it, seller_custom_field, is for the seller’s internal use and has no relation to it. Where a listing does not carry it, the match has to come from a table built by hand.
So the first table of the project is the mapping between listings and items: for each listing, and for each of its variations, the item of the ERP it sells. It can be built from the seller’s code, where your listings carry it, or by hand, with someone who knows both. Either way, a line whose listing has no item in the table does not become an order line with a guess: it waits, with the reason, for a person to decide.
Orders and packs
A purchase of several products in one cart reaches Mercado Libre as several orders, and the documentation says to read the orders of a cart purchase through the packs resource. A pack is not only a cart, though: the documentation says that, gradually, every order is being linked to a pack, and that a pack can hold one or more orders, from the same seller or from different ones.
For the ERP this is a choice to make on purpose. One ERP order per Mercado Libre order keeps the key simple and mirrors the platform. One ERP order per pack, with only your own orders in it, mirrors what the buyer did and what the warehouse ships: the documentation gives a pack at most one shipment, unless that shipment is split. Neither is wrong. What matters is to choose, to write it down, and to use the matching key everywhere, from the duplicate check to the cancellations.
The status, and when stock is taken
An order existing does not mean it can be prepared. The statuses the documentation lists run from confirmed and payment required to paid, partially refunded, pending cancellation and cancelled. An order’s closing date is set when it first becomes confirmed or paid, and that is when the stock of the listing is discounted. The documentation also describes a case no connection can ignore: if a fraud alert arrives after the payment, the order is marked with the fraud_risk_detected tag, a notice goes out on the orders topic, the goods must not be shipped and the order has to be cancelled.
The rule worth writing down is easy to state: the order goes into the ERP as soon as Mercado Libre confirms it, but the warehouse sees it as ready to prepare only when its status allows it. And a later change, a cancellation or a fraud alert, reaches the ERP and the warehouse by the same road as the order.
The buyer, and the data for the invoice
The connection receives the buyer data Mercado Libre shares, and no more. That is enough for an order, but not necessarily for an invoice. The billing data of a sale are read in a separate step: the order gives the identifier of the buyer’s billing information, and a separate resource, per site, returns the name, the identification document and its type, the taxpayer type and the address. The older resource for the same data is deprecated.
One change in that resource matters for the ERP: the field that used to say which type of invoice to issue has been removed, and the documentation now says that deciding the invoice type is entirely up to the integrator, based on the buyer’s identity document. For Argentina it fixes the mapping: a CUIT gives an invoice of type A, a DNI one of type B. Elsewhere the rule is your accounts team’s, under each country’s tax rules.
The shipment
The order carries the identifier of its shipment, whose details are read separately. Among them is the logistic type, which says where the parcel is prepared and how it travels: from your own warehouse, in one of the ways Mercado Libre offers, or from Mercado Libre’s centres, when the type is fulfillment, which is Full. That field decides two things in the ERP: whether the order goes to your warehouse at all, and whose stock it consumes.
The shipments resource is also a reminder that the API moves. According to its documentation, since 12 October 2025 every request has to send the x-format-new header, which asks for the newer format, and two fields of the older one, order_id and external_reference, are no longer returned. It also says that the buyer’s address is not shown until the payment is confirmed. A connection written once and left alone breaks on a day nobody chose.
Stock: which warehouse feeds which listing
Stock is the flow that goes the other way, and the one where mistakes are seen by buyers first.
Updating a listing
On Mercado Libre, the available quantity of a listing is updated through the listings resource; for a listing with variations, the quantity is sent for each variation. The connection sends the quantity your rule says, not the raw figure of the warehouse, and it sends it when that figure changes, not once a day.
Two kinds of pause
The documentation describes two different pauses. A listing that runs out of stock is paused by itself, and reactivated by itself when units are added again. A listing that the seller pauses, on the other hand, is not reactivated by new stock: it stays paused until the seller reactivates it. A connection that does not tell the two apart can leave listings paused that should be on sale, and no one notices until sales drop.
Stock of the product, by location
Mercado Libre is moving sellers to a newer model, User Products, in which several listings can belong to the same product. Unless the account uses stock from several origins, Mercado Libre keeps the stock of all the listings of one product in step by itself. The stock is read per product and per location, and the documentation names three kinds of location: Mercado Libre’s own facilities, for Full; the seller’s origin warehouse for the shipping methods other than Full (selling_address); and the seller’s own warehouses, when the account uses the multi-origin model (seller_warehouse). Updates go to the seller’s locations, in the forms each country and each account allows.
One detail of that resource is good design in itself. Every update has to carry the version of the stock it was computed from: an update without it is refused, and one based on a version that has changed meanwhile is refused too. The connection reads the stock, computes, and sends with the version it read; when the answer is that the version changed, it reads again instead of overwriting a change it never saw.
Full: read, never written
If you use Full, Mercado Libre stores your stock and prepares each order. The stock in its facilities cannot be edited through the API: according to the documentation, it can only be increased by sending products to the Full warehouses, from Mercado Libre’s panel. The documentation also says that Full stock and the stock of your own locations are entirely independent. The orders of those units still come into the ERP, because they are sales of your company, but they are not sent to your warehouse to prepare.
The rule, written down
A stock rule fits in a few lines, and it should be written by whoever decides commercially, not by whoever writes the code. For example, and only as an example: on Mercado Libre Mexico, show the units of the Mexican warehouse; below five units, show nothing; for the units in Full, send nothing. Each company will have its own rule. What it cannot lack is the answer to three questions: which warehouse feeds each site, how many units are shown, and what happens when few are left.
The payment: from Mercado Pago to the order
The sale is in the ERP and the stock has moved. What is left is the money, and the money lives on the other platform.
Where the payment is
A Mercado Libre order carries a list of its payments, each with its identifier and its status. That identifier is the bridge: for the detail of a payment, Mercado Libre’s documentation sends you to the payments resource of Mercado Pago, read with that identifier. Because it is a list, a sale and a payment are not always one to one, and the connection has to accept an order with more than one.
What a payment says
Reading a payment returns its status, among them pending, approved, in process, in mediation, rejected, cancelled, refunded and charged back, with a detail of why; the date it was approved; the amount; the breakdown of its charges, each with its type and who pays it; and the net amount received. The net amount is what the payment adds to your Mercado Pago balance once its money is released; how the charges are posted is your accountant’s decision.
When the money is available
Each payment also carries the date on which it is settled and its money is made available in your Mercado Pago account. Until that date the money is in the account but not yours to move. Mercado Pago’s documentation adds a field that changes the reading of a payment in instalments: for a payment in instalments released «in flow», the money comes in month by month; for any other payment the field is empty.
For the ERP, this means a payment is not one fact but two: the buyer has paid, and the money is available. The order can be marked as paid on the first; the money can be counted as yours to move on the second.
Payouts: from the Mercado Pago account to your bank
This is where month-end confusion starts, because what reaches the bank is not a payment.
The available balance of your Mercado Pago account is made of released payments, net of their charges, and of every other movement the reports list: refunds, chargebacks, money held for claims, taxes withheld, the shipping fee of a cart charged apart from its payments. Claims can affect money even after it has been released. What reaches your bank is a withdrawal from that balance, not one transfer per sale.
Mercado Pago’s reports are what connect the two ends. In the released money report, the Reporte de Liquidaciones, each withdrawal appears with the balance before and after it, and with the number of the account the money was sent to. The amount on the bank statement is explained by the movements of that report, not by a list of payments it carries. The report of all transactions covers the money available, the money still to be released, and the money held. The documentation also warns of something worth reading twice: the total of the report may not always match your balance, or the total of the billing reports.
Recording each payment against its order is the work of a connector. Explaining each withdrawal on the bank statement by the movements behind it, and matching each payment with its fees and withholdings, is a reconciliation, a job of its own: it is what our Local payments reconciled service does.
To see it for yourself, download last month’s Reporte de Liquidaciones and find the rows of one withdrawal: the balance before it, the balance after it, and the account it went to.
When a sale goes back
Not every sale stays a sale. The connection has to bring the reversals into the ERP by the same roads as the sales.
Cancellations and refunds
A cancelled order changes its status on Mercado Libre, and the notice of the order reports it like any other change. The documentation adds that a paid order is cancelled if its payment is refunded, and it describes a different refund flow, for now only for sellers in Mexico and announced for Argentina and Brazil, for buyers with a good reputation who pay by card: when a cancellation is refunded to the buyer’s Mercado Pago balance, the order never reaches the cancelled status; it stays paid, with a tag that says it was not fulfilled, and the payment carries a tag of its own for the refund. A connection that waits for the cancelled status will never see that one. The rule has to read the tags too.
The ERP order follows what happened: it is cancelled, or partly refunded, and the stock it had taken is given back where your rule says so.
Claims and returns
On Mercado Libre, returns are read starting from claims. The documentation recommends listening to the notices of claims, reading the claim, and checking whether a return is among its related entities; if there is one, reading it through its own resource. It distinguishes three kinds of return: one started through a buyer’s claim, one that results from a dispute, and one the buyer starts and the system processes automatically. For the ERP, a return is a document linked to its order, not a new one: the goods that come back, and the money that goes back, belong to the sale they undo.
What the connection keeps for people
A connection that works by itself still needs a place where people see what it could not do. Most of the cases have appeared above: a line whose listing has no item, an order of a site no company is assigned to, a sale whose billing data are missing, a stock update still refused after reading the stock again, an authorisation that ended. Each one stops that document, not the others, and appears in a list with its reason and the order it belongs to.
That list replaces the morning routine. The person who used to type the sales now looks only at the ones the connection could not record, if there are any, and fixes the cause: the missing code on the listing, the missing item in the table, the rule nobody had written. When the cause is fixed, the connection processes the document again.
Testing before the first real sale
With no sandbox, the test is designed on purpose. Create the test users, publish test listings that match test items in a test company of the ERP, and buy with one test user from the other. The documentation sets the rules: a test listing is titled «Item de Prueba - Por favor, NO OFERTAR», it is never published in the gold or gold_premium listing types, and the buyer pays with test cards. To test User Products or stock in several warehouses, Mercado Libre has to set up your test users first, on request through a form; for stock in several warehouses it does so on Fridays, every fifteen days. Then go through the cases that teach the most: a cart of several products, a listing with variations, a listing with no item in the table, a cancellation, and a sale that runs a listing out of stock. Each one has to end in the ERP with the right document and, where it stopped, the reason in sight. The documentation describes no way to try Full with test users: check it on the first real sales in Full. Mercado Pago’s reports will not help here: the documentation says that the reports of test accounts are empty.
Then turn the connection on for real with one site, and for the first weeks compare every morning what Mercado Libre shows with what the ERP has. When they agree for long enough, the morning routine this piece started from can stop.
An example, from start to finish
A maker of motorcycle spare parts in Italy, imaginary like the examples on our pages, has subsidiaries in Chile and Colombia that sell the same parts on Mercado Libre, each in its own country and currency, from its own warehouse, with Business Central as the ERP of the group. Sales are typed in at the end of each day; in the busy season they pile up, the warehouse ships orders that are not in the system yet, and the stock in Business Central still counts parts that have already gone out.
The project starts with the decisions, not the code. Each site is assigned to its subsidiary’s company and currency. Each ERP order is one Mercado Libre order. The mapping table is built from the seller’s code, which most listings carry, and a person from each subsidiary fills in the rest. The stock rule fits in two lines: each site shows its own warehouse, and nothing below three units. An administrator of each account authorises the application, and the group writes down who that is.
Then the test, with test users and test listings, through the cases of the previous section, and then one subsidiary for real. For the first weeks the morning check compares the sales of the day with the orders in Business Central. What stops is shown with its reason: in the first days, mostly listings without the seller’s code, which are fixed at the source. When the first subsidiary has run clean for long enough, the second follows. The warehouse now prepares from orders that are already in the system, and the stock in Business Central counts the parts that have left.
Where to start this week
None of these needs a project decided first:
- Write down on which Mercado Libre sites you sell, and which company of your ERP each one belongs to.
- Count how many of your listings carry your item code in the seller’s code, and list the ones that do not.
- Write the stock rule in three lines: which warehouse feeds each site, how many units are shown, what happens when few are left.
- Note which listings have units in Full, and which of those also ship from your warehouse.
- Find out which administrator user would authorise the connection, on each account.
How we do it
This is the work of our Mercado Libre and Mercado Pago connector, as its page describes it. First we look with you at how you sell on Mercado Libre: in which countries, with which listings, and how you collect payments through Mercado Pago. We match each listing to its item in the ERP. Then you authorise the connection with your account’s administrator user, on Mercado Libre and on Mercado Pago; we connect it to your Business Central or SAP Business One, and we test it with your team before leaving it running.
From then on every sale goes into the ERP as an order, the stock held in the system is updated on the listings you ship from your own warehouse, and every Mercado Pago payment is recorded against its order. Listings in Full keep their stock in Mercado Libre’s warehouse: the connector records their sales as orders, but does not change that stock. When Mercado Libre or Mercado Pago change their APIs, we update the connector, as part of the service you pay for with the fee, which is written down before we start.
If you want to see how it would work in your case, start with a free one-hour video call: tell us where you sell and which ERP you use, and we will tell you what we would connect first.
The sources we cite
- Mercado Libre Developers: Autenticación y Autorización, Notificaciones, Realiza pruebas and Dominios y Categorías.
- Mercado Libre Developers: Gestionar órdenes, Gestión de packs, Gestiona pagos, Datos de Facturación and Billing info.
- Mercado Libre Developers: Gestionar envíos, Gestión Mercado Envíos and Envíos Fulfillment.
- Mercado Libre Developers: Sincroniza y modifica publicaciones, Variaciones, User Products, Stock distribuido and Stock Multi Origen.
- Mercado Libre Developers: ¿Qué es un reclamo? and ¿Qué es una devolución?.
- Mercado Pago Developers: Obtener pago, in the API reference.
- Mercado Pago Developers: Reportes, the Reporte de Liquidaciones and its fields, and the Reporte de Todas las transacciones.
What we do about it: Mercado Libre and Mercado Pago connector