PlatformMarketplacesPricingDashboardStart for free
Link sessions

Create a link session

Generates the links for the seller to connect marketplaces, through our page or a button in your app.

POST
/v1/sellers/{id}/link-sessions

Creates the connect session of a seller and returns two kinds of link. Both share the same deadline and show up only in this response.

  • url, the hosted page. Send it to the seller (email, message). They pick the marketplace, authorize on the marketplace screen and come back to the page, which shows the connected account.
  • connectUrls, one link per marketplace to put behind your own "Connect" button. Opening it takes the seller straight to the marketplace consent screen; after authorizing, they land on your redirectUrl with ?connected=<marketplace> (or ?error=<code>). Our page is never in the way. Without a redirectUrl, they land on the hosted page instead.

Either way, exchanging the code for a token and renewing it is on us: the seller only sees the marketplace and your app.

  • allowedMarketplaces limits the marketplaces offered and the keys of connectUrls. Without it, every marketplace available in this environment is offered.
  • redirectUrl is where the seller lands at the end: after the Finish button of the page, or right after the marketplace when they came through a connectUrls link. It must be https.
  • app picks the marketplace app the seller authorizes: auto (default) uses your own app (BYOK) when you registered one for that marketplace, and ours otherwise; platform always uses ours. A connection keeps the app it was made with. See BYOK.
  • expiresInMs is the deadline of the links: from 1 to 5 min, default 5 min. Create the session when the seller is about to click, not earlier.

Send an Idempotency-Key: if the response is lost, repeating the request with the same key returns the same links, without creating another session.

?error= codes

CodeMeaning
authorization_deniedThe seller did not authorize on the marketplace screen.
authorization_failedThe marketplace refused the code exchange (account without administrator rights, expired code). Create a new session.
session_unavailableThe session expired, was revoked or completed before the seller finished.
marketplace_unavailableThe marketplace is not available in this environment or in this session.

Common errors

  • 400 VALIDATION_ERROR with details.unavailable: a requested marketplace is not available in this environment.
  • 400 VALIDATION_ERROR with details.field set to redirectUrl: the redirectUrl is not https.
  • 400 VALIDATION_ERROR without details: expiresInMs outside 1 to 5 min.
  • 404 NOT_FOUND: the seller in the path does not exist or belongs to another account.

Authorization

api_key
headerAuthorizationBearer <token>

API key (mk_...)

Path Parameters

id*string

Identifier of the resource, as returned by the API.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid

Header Parameters

Idempotency-Key?string

Optional. A unique value (for example a UUID), 1 to 255 characters, that makes the request safe to retry: repeating it with the same body within 24h returns the original response with Idempotency-Replayed: true instead of running the operation again. Scoped to your account. Reusing it with a different body returns 409.

Length1 <= length <= 255

Request Body

application/json
  1. body
allowedMarketplaces?array<>

Optional. Marketplaces the page offers, at least one and no repeats. Omit it to offer every marketplace available in this environment; one that is not available returns 400.

Items1 <= items
redirectUrl?|

Optional. An https URL, up to 2048 characters, where the seller lands at the end: the Finish button of the hosted page sends them there, and so does the marketplace callback when the seller came through one of the connectUrls (with ?connected=<marketplace> or ?error=<code> appended). The contract accepts http too, for development and e2e, but the API refuses a non-https URL outside development. Omit it or send null and the page just thanks them.

Formaturi
Lengthlength <= 2048
app?string

Optional. Which marketplace app the seller authorizes. auto (default): your own app when you registered one for that marketplace in the dashboard, ours otherwise. platform: always ours, even when you have your own. A connection keeps the app it was made with for its whole life.

Default"auto"
Value in"auto""platform"
expiresInMs?integer

Optional. How long the page and the connectUrls work, in milliseconds: from 60000 (1 min) to 300000 (5 min). Defaults to 300000 (5 min).

Range60000 <= value <= 300000
Default300000

Response Body

The link session was created. The body carries url, the hosted page to send to the seller, and connectUrls, one link per marketplace to put behind your own button; both show up only here.

application/json
  1. response

The new link session, with the URL of its hosted page and the per-marketplace connect links.

id*string

Opaque unique identifier of the link session, generated by the API. Use it in the /v1/link-sessions/{id} routes.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
sellerId*string

The seller who connects through this session.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
status*string

State of the session. pending: open and within its deadline. completed: the seller clicked Finish. expired: expiresAt passed before that. revoked: you revoked it.

Value in"pending""completed""expired""revoked"
allowedMarketplaces*array<>

Marketplaces the hosted page offers.

app*string

The app choice made when the session was created: auto or platform.

Value in"auto""platform"
redirectUrl*|

Where the seller lands at the end: after Finish on the hosted page, or right after the marketplace when they came through a connectUrls link. null when the page just thanks them.

connectionIds*array<>

Connections made, or made again, through this session.

expiresAt*string

When the hosted page stops working, in ISO-8601 (UTC).

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
completedAt*|

When the seller clicked Finish, in ISO-8601 (UTC). null before that.

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
createdAt*string

When the session was created, in ISO-8601 (UTC).

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
url*string

The hosted page to send to the seller. It shows up only in this response (and in the replay of the same Idempotency-Key): we keep only a hash of it.

Formaturi
connectUrls*

One link per marketplace in allowedMarketplaces, to put behind your own "Connect" button instead of sending the seller to the hosted page. Opening it takes the seller straight to the marketplace consent screen; after authorizing, they land on your redirectUrl with ?connected=<marketplace> (or ?error=<code>), never on our page. Without a redirectUrl they land on the hosted page instead. Same deadline as url; shows up only in this response.

curl -X POST "https://example.com/v1/sellers/3d1c8a52-7f0e-4b0a-8a65-9c1b2f6d7e01/link-sessions" \  -H "Content-Type: application/json" \  -d '{    "allowedMarketplaces": [      "mercadolivre"    ],    "redirectUrl": "https://your-app.com/connected"  }'
{  "id": "5b2f0c1e-8d3a-4f6b-9c21-7e4d3a2b1c00",  "sellerId": "3d1c8a52-7f0e-4b0a-8a65-9c1b2f6d7e01",  "status": "pending",  "allowedMarketplaces": [    "mercadolivre"  ],  "app": "auto",  "redirectUrl": "https://your-app.com/connected",  "connectionIds": [],  "expiresAt": "2026-10-06T14:45:00.000Z",  "completedAt": null,  "createdAt": "2026-10-06T14:30:00.000Z",  "url": "https://marketapi.shop/connect/Zq3kR8vN2xLm5pT7wY1aB4cD6eF9gH0jK2lM4nP6qRs",  "connectUrls": {    "mercadolivre": "https://api.marketapi.shop/connect/Zq3kR8vN2xLm5pT7wY1aB4cD6eF9gH0jK2lM4nP6qRs/mercadolivre/start?return=client"  }}

Overview

What a link session is and the rules that apply to all of its endpoints.

Get a link session GET

Reads the state of a link session and the connections made through it.