Data model
Every resource in the API, how they connect and the rules that apply to all of them.
This section shows the whole data model: what each resource represents, who owns it and how it connects to the others. The detail of each field and endpoint is on each resource's pages, in the API group of the sidebar.
The map
How to read the lines. Each line connects two resources, and its end says how many exist on that side:
| End of the line | Means |
|---|---|
| two bars | exactly one |
| a circle and a bar | zero or one |
| a circle and a crow's foot | zero or more |
| a bar and a crow's foot | one or more |
Example: between Product and Variant, the end on the Variant side has a bar and a crow's foot. Read "a Product has one or more Variants". The Product side has two bars: "each Variant belongs to exactly one Product".
The resources in one sentence
| Resource | What it is | Belongs to | Who creates it |
|---|---|---|---|
| Account | Your company. It has the dashboard login and the API keys. | — | you, in the dashboard |
| Seller | Your customer: the merchant. They have no marketapi login. | Account | POST /v1/sellers |
| Link session | The page where the Seller connects a marketplace. It lasts up to 5 minutes. | Seller | POST /v1/sellers/{id}/link-sessions |
| Connection | One of the Seller's marketplace accounts, such as a Mercado Livre account. | Seller | the Seller, by granting access in the link session |
| Product | The base record: what the Seller sells. No price and no marketplace. | Seller | POST /v1/sellers/{sellerId}/products |
| Variant | A sellable combination of the Product (color, size). It has its own SKU, GTIN and stock. | Product | the API creates the first one; the others, POST /v1/products/{productId}/variants |
| Component | One line of a kit's recipe: which Variant and how many units. | Product (the kit) | PUT /v1/products/{productId}/components |
| Warehouse | Where the Seller keeps the goods. Every Seller starts with a default warehouse. | Seller | the API creates the default one; the others, POST /v1/sellers/{sellerId}/warehouses |
| Inventory movement | One stock entry or exit in a warehouse. It never changes after it is created. | Variant and warehouse | POST /v1/sellers/{sellerId}/inventory-movements |
| Inventory balance | The Variant's balance in each warehouse, computed from the movements. The Variant sums the warehouses. | Variant and warehouse | the API |
| MarketplaceProduct | The content of an item on the Connection: title, attributes, media. Shared between offers. | Connection | POST /v1/sellers/{sellerId}/listings (creates it), a clone or an import |
| Marketplace product variation | The variation of the content: links the content to a Variant and keeps the variation id there. | MarketplaceProduct | PUT /v1/marketplace-products/{id}/variants, the binding or an import |
| Listing | The offer on a Connection: price and limits, on top of a MarketplaceProduct. | Connection | POST /v1/sellers/{sellerId}/listings or an import |
| Variant binding | One line of the offer: it sells a variation of the content, with the line id there. | Listing | PUT /v1/listings/{listingId}/variant-bindings or an import |
| Job | Background work: publishing, importing, sending stock. | Account (and the Seller, when the work is for one) | the API, when the operation talks to the marketplace |
| Webhook endpoint | A URL of yours that receives the events. | Account | POST /v1/webhooks/endpoints |
| Webhook delivery | One delivery of an event to an endpoint, with its attempts. | Webhook endpoint | the API, for every event |
Two sides that meet at the offer
The model has two sides. The catalog says what the Seller sells. The channels say where they sell it. The channel side keeps no product and no stock: the content (MarketplaceProduct) points to the catalog's Variants through its variations, and the offer (Listing) sells those variations through the variant binding.
That is why:
- One Product can be in many listings, on many marketplaces, or in two offers of the same content to test a price.
- There is one stock. It belongs to the Variant, not to the offer, and sits in the Seller's warehouses. Every movement you record changes the same balance, whichever offer the sale came from.
- The marketplace never changes the catalog. What changes out there is kept in the MarketplaceProduct and in the Listing (
observed), and the Product stays as you left it.
Around it: jobs and webhooks
Two pieces follow everything else and belong to the Account:
- Job: every operation that talks to the marketplace answers right away with a Job and goes on in the background. Each Job has items, one per resource. See Tracking jobs.
- Event and delivery: every change that matters to you becomes an event. Each event becomes one delivery for each endpoint subscribed to it. See Receiving webhooks.
Rules that apply to everything
The Account isolates everything. An id from another Account returns 404, the same as an id that does not exist.
The Seller is the owner. Products, Variants, warehouses, MarketplaceProducts, Listings, Connections, link sessions and inventory movements belong to a Seller. A resource only connects to another one of the same Seller: a listing never points to another Seller's Variant.
Where the Seller goes in the request:
| Operation | Where the Seller goes | Example |
|---|---|---|
| Create something for the Seller | in the path | POST /v1/sellers/{sellerId}/products |
| List connections or inventory movements | in the Seller-Id header | GET /v1/connections with Seller-Id: … |
| Read, change or delete by id | nowhere: the id is enough | GET /v1/listings/{listingId} |
| List products, listings or jobs | nowhere: the whole Account comes back | GET /v1/products; each item has its sellerId |
Ids. Every resource's id is a UUID generated by the API. The Seller also takes an externalId: their id in your system. Marketplace ids arrive in their own fields: externalAccountId on the Connection, externalId on the MarketplaceProduct, externalVariantId on the variation, externalId and externalSku on the binding, observed.marketplaceId on the Listing.
Units. Money is always in cents, as an integer, next to the currency: priceInCents: 799900 with currency: "BRL" is R$ 7,999.00. Weight in grams (weightInGrams) and dimensions in millimeters (dimensionsInMm), also integers. Dates in ISO 8601 with a time zone.
Delete or archive.
- Seller:
DELETEremoves it for good, and only when it has no active connection (otherwise409withdetails.reason = "active_connections"). There is no trash. - Product and Variant:
DELETEarchives. The history and the inventory movements stay. - Warehouse:
DELETEarchives. It does not archive the default one or a warehouse with balance (409,details.reason = "warehouse_in_use"). - MarketplaceProduct: it has no
DELETE. Without an offer, it keeps existing. - Listing:
DELETEtakespublication, which decides whether the listing also leaves the marketplace.
The example in this guide
The next pages always use the same case. Acme Store is one of your Sellers. It connected a Mercado Livre account and sells:
- an iPhone 16 in two colors, black and white, both with 128 GB;
- a USB-C cable and a 20W charger, each sold on its own;
- a charging kit, made of 2 cables and 1 charger.
The catalog. Four Products. The iPhone has two Variants. The others only have the default Variant. The kit consumes Variants of the other Products:
The listings. Two MarketplaceProducts and two Listings on the Mercado Livre Connection. Each content points, through its variations, to the Variants it sells, and each Listing is the offer of its content:
In both drawings, a solid line means "has". A dashed line points to a Variant: a variation of the content (the lines of the offer, the bindings, sell those variations), or a component of the kit with how many units it consumes.
Where to go next
Catalog and inventory
Product, Variant, kit and how the balance is computed.
Connections and listings
Connection, MarketplaceProduct, Listing, binding and where each published field comes from.
States and events
The lifecycle of each resource and the webhook for each change.
Integrating with an AI assistant?
The whole documentation is in plain text, in one file, at
/llms-full.txt, with the diagrams in Mermaid format. The
index is at /llms.txt.