Stay in sync
Stock that goes out on its own, changes that come back from the marketplace and how to settle differences.
Once published, a listing lives in two places: on marketapi and on the marketplace. This phase keeps both the same. What you want lives in desired. What the marketplace confirmed lives in observed. The seller's catalog never changes because of the marketplace.
1. The sync policy
Each Listing has a policy with three parts:
| Part | Values | What it decides |
|---|---|---|
outbound | enabled: true or false | whether publish commands may call the marketplace |
inbound | active or disabled | whether changes made out there are saved in observed |
inventory | automatic or manual | whether each balance change publishes the quantity on its own, and on which lines |
2. Automatic stock
With inventory: automatic, every balance change publishes available on each chosen line of the offer. It does not matter where the change came from: a movement of yours, an order's reservation, a return.
At Acme Store: the black iPhone's balance drops from 100 to 99. marketapi creates a job and sends 99 to every listing of that iPhone, on Mercado Livre, Amazon and Shopee. At the end, inventory.published arrives.
- Kits follow. Selling a cable changes the kit's balance, and the kit is published too.
- Only quantity goes out on its own. Price, title and photos only go to the marketplace when you publish.
- One call for shared stock. Where the marketplace shares stock between offers, marketapi publishes once. The Connection says so in
inventory.scope. - With
manual, you choose when to resend.
3. What changes on the marketplace
The seller may change a price right in the Mercado Livre panel. marketapi finds out in two ways:
- Notification: the marketplace tells it right away.
- Reconciliation: every 6 hours, marketapi compares everything. This catches what a notification missed.
The change goes to observed and listing.external_changed arrives. When the status changes (paused, under review, out of stock), listing.status_changed arrives with the reason.
A conflict is when both sides changed the same field: you changed the price here and have not published yet, and the seller changed it there. marketapi does not choose. listing.conflict_created arrives, and you resolve it: keep_local (your value stays), accept_external (theirs stays), inherit (your override goes away) or manual (you send the value). Resolving never publishes.
To understand a listing, use:
diff: what changed here and what changed there since the last publication;issues: what blocks publishing or selling;activity: the listing's history;publish-attempts: each publish attempt, with the error.
4. Stock in the marketplace's warehouse
Some marketplaces keep the product in their own warehouse, such as Mercado Livre Full and Amazon FBA. There, the marketplace counts the stock:
- The Connection's stock locations say what belongs to the seller (marketapi publishes) and what belongs to the marketplace (read only).
- The fulfillment map says which of the seller's warehouses feed each location.
- A fulfillment inbound shipment records units sent to the marketplace's warehouse.
When what marketapi published and what the marketplace says it has do not match, a discrepancy is born, with the inventory.discrepancy_detected event. You check and settle it.
5. Is everything up to date?
The Connection's sync state shows, per resource (listings, orders, questions…), the last full read, the last notification and the next reconciliation. To force a read, ask for a reconciliation.
Endpoints in this phase
| To | Endpoint |
|---|---|
| Set up sync | See policy · Change policy |
| Resend stock | Resend stock |
| See what is there | Observed · Differences · Issues · History |
| Settle conflicts | List conflicts · Resolve |
| Force a read | Reconcile listings · Refresh one listing |
| Stock at the marketplace | Locations · Map · Discrepancies · Inbound shipments |
| See the state | Sync state |
Webhooks in this phase: inventory.published, listing.external_changed, listing.status_changed, listing.conflict_created, listing.conflict_resolved, inventory.discrepancy_detected and fulfillment_inbound_shipment.updated.