Connecting a seller

The seller connects their accounts on our page. You create the session through the API, send them the URL and find out through the webhook — or by reading the session.

The examples use Authorization: Bearer mk_your_api_key and SELLER_ID with the id of a seller.

1. Create a link sessionCopy Anchor Link

curl -X POST $BACKEND_URL/v1/sellers/$SELLER_ID/link-sessions \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"redirectUrl":"https://your-app.com/connected"}'

Without allowedMarketplaces, the page offers every marketplace of this environment. Asking for one that does not exist here (for example amazon, or mock in production) gives 400 with details.unavailable. In development, use mock (see the end of this page).

The 201 response carries the page url and, in connectUrls, one link per marketplace for your own button. They show up only here (and in the replay of the same Idempotency-Key) and last at most 5 minutes, so create the session at click time. Fields and errors are in Create a link session.

2. The seller connectsCopy Anchor Link

Two paths, your choice:

• Through our page. Send the url to the seller. They pick the marketplace, authorize on the marketplace screen and come back to the page, which shows the connected account. They can connect more than one marketplace, and more than one account on the same one. Finish closes the session and takes them to your redirectUrl, if you sent one. The page has a language picker (Portuguese and English).
• Through your app. Put connectUrls.mercadolivre behind your "Connect Mercado Livre" button. The seller goes straight to the marketplace consent screen and comes back to your redirectUrl with ?connected=mercadolivre (or ?error=<code>), without ever seeing our page. Exchanging the code for a token and renewing it stays on us.

On Mercado Livre, only the administrator account can authorize; an operator or collaborator user gets an error.

3. You find outCopy Anchor Link

Through the webhook: connection.created for each connected account and link_session.completed when the seller clicks Finish. Or read the session: Get a link session returns its status and connectionIds.

4. Use the connectionsCopy Anchor Link

The list is per seller, with the Seller-Id header:

curl "$BACKEND_URL/v1/connections?status=active" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Seller-Id: $SELLER_ID"

Each connection carries status: active works (we refresh the token on our own); revoked and error need a new link session (revoked: you or the marketplace ended the access; error: renewing failed in an unexpected way). Details in Connections. To disconnect: Disconnect.

Development: the mock marketplaceCopy Anchor Link

Outside production there is the mock marketplace: authorization is instant, with no account anywhere. To simulate the marketplace revoking access to a mock connection (CONNECTION_ID is its id, as GET /v1/connections returns it):

curl -X POST $BACKEND_URL/inbound/mock/$CONNECTION_ID \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"topic":"deauthorization"}'

connection.revoked arrives within seconds, with revokedReason: "marketplace". In production this route answers 404.