Overview
A connected marketplace account and the control point for its operations.
A Connection is a marketplace account linked to a Seller: for example, one Mercado Livre account. It is created when the Seller authorizes access through a link session, the hosted page, or a button embedded in your app. The Connection contains protected credentials, external account identity, and import rules; Products, Variants, and Listings remain separate resources.
How the Connection connects to listings and to the catalog, with diagrams: Connections and listings.
From connected seller to synchronized listing
- Create a link session and let the Seller authorize the marketplace. Then confirm that the Connection is
active. - Read Connection capabilities. They are the actual execution contract of that adapter — do not assume every channel can publish, import, or update inventory.
- Choose the import policy: observe only, link exact matches, or create a minimum record when no match exists.
- Import existing listings. The response is a Job; results become Listings with external state in
observed. - Review unlinked Listings, associate their Variants, and configure synchronization policy. To recover from a missed notification or check the channel again, reconcile.
- Use Listing and Inventory endpoints to edit locally and publish only when capability and policy allow it.
Current support
The indicators below show static product availability. Read the complete marketplace matrix for every feature; before a command, the Connection capabilities response remains the execution decision.
Connect
- MockDevelopment only
- Mercado LivreSupported
- MagaluPlanned
- AmazonPlanned
- TikTok ShopPlanned
- ShopeePlanned
Bring your own app
- MockDevelopment only
- Mercado LivreSupported
- MagaluPlanned
- AmazonPlanned
- TikTok ShopPlanned
- ShopeePlanned
Native notifications
- MockDevelopment only
- Mercado LivreSupported
- MagaluPlanned
- AmazonPlanned
- TikTok ShopPlanned
- ShopeePlanned
Import listings
- MockDevelopment only
- Mercado LivreNot supported
- MagaluPlanned
- AmazonPlanned
- TikTok ShopPlanned
- ShopeePlanned
Connection endpoints
| Goal | Endpoint |
|---|---|
| See a Seller's Connections or one Connection | List · get |
| Discover what the adapter actually supports | Connection capabilities |
| Define how listings are imported and linked | Get · update |
| Read external listings now | Import |
| Revalidate external snapshot later | Reconcile |
| See how each resource is kept in sync | Synchronization state |
| Discover categories, requirements, brands, types, size charts and catalog | Categories · requirements · brands · product types · size chart · delivery modes · catalog · catalog product |
| See stock locations and link warehouses to them | Locations · mapping · update mapping |
| Bring in orders and set how they move stock | Import · reconcile · policy · update policy |
| See the account's reputation | Health |
| Use what has no common model, with no proxy | List · describe · run |
| Options only one marketplace has | Get · update |
| End account access | Disconnect |
Every listing is per Seller. To see what a Seller has connected, send their id in the Seller-Id header:
curl "$BACKEND_URL/v1/connections?status=active" \
-H "Authorization: Bearer mk_your_api_key" \
-H "Seller-Id: $SELLER_ID"Every endpoint requires Authorization: Bearer mk_your_api_key. See Authentication. The Seller-Id header exists only for listing; to read, operate, or disconnect a Connection, its id is sufficient.
States
| status | Meaning | What to do |
|---|---|---|
active | usable credentials and permitted operations | may import/publish if capability exists |
revoked | client or marketplace ended access | create a new link session to reconnect |
error | an operation failed definitively without proving revocation | reconnect and investigate Job/webhook |
revokedReason: "client" indicates a disconnect you ordered;
"marketplace" indicates the channel removed or refused to renew
access. Reconnecting the same external account restores the same Connection and
its id; status changes arrive by webhook. Temporary failures do not make a
Connection inactive by themselves: Jobs may retry.
App and isolation
app says whether the Seller authorized the platform app (
platform) or the app credential you registered (own,
BYOK). A Connection retains that choice until its next reconnection. Connection
IDs from another account respond as nonexistent (404) so they never
disclose third-party data.