Overview
What a seller is and the rules that apply to all of its endpoints.
A seller is your customer: the merchant who will connect marketplaces through you. They have no login on marketapi. Each seller belongs to one account, and only that account can see it.
How the Seller connects to every other resource, with diagrams: Data model.
Endpoints
| Method | Path | What it does |
|---|---|---|
POST | /v1/sellers | Create a seller |
GET | /v1/sellers | List sellers |
GET | /v1/sellers/{id} | Get a seller |
PATCH | /v1/sellers/{id} | Update a seller |
DELETE | /v1/sellers/{id} | Delete a seller |
All of them require Authorization: Bearer mk_your_api_key. See Authentication.
A seller's connections
Every seller carries connections: the short list of the marketplace accounts they have connected and working (status: active), newest first, with id, marketplace, marketplaceDisplayName and status. Empty when there is none. It is enough to know where the seller is connected straight from the listing, with no second call.
"connections": [
{ "id": "9a1b2c3d-…", "marketplace": "mercadolivre", "marketplaceDisplayName": "Mercado Livre", "status": "active" }
]The full record (external account, scopes, token expiry) and the other states (revoked, error) live in List connections, with the seller's 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"There is no GET /v1/sellers/{id}/connections: the seller goes in the path when the operation creates something of theirs (like POST /v1/sellers/{id}/link-sessions) and in the header when it lists by seller. To connect a new account, create a link session.
Two ids: id and externalId
idis ours: a UUID generated at creation. It is the one that goes in the URL (/v1/sellers/{id}).externalIdis yours, and optional. Use your customer's id in your system to find the record without storing ours.
externalId is unique within your account. Another account may use the same value. Repeating a value in your account returns 409 CONFLICT.
A seller from another account
An id that does not exist and an id that belongs to another account get the same answer: 404 NOT_FOUND. This way nobody can discover ids of other accounts.
Metadata
Store your own data on the seller (plan, region, CRM id, tags) and filter the list by it. See Metadata.
Pagination
The list returns one page at a time, from the newest seller to the oldest. You choose the page with page (starting at 1) and the size with pageSize (1 to 100, default 20). The pagination of the response has the totals (totalItems, totalPages) and tells if there is a page after (hasNext) and before (hasPrev). The step by step is in List sellers.
Deletion
Deleting a seller is permanent: there is no trash and no undo.
A seller with an active connection cannot be deleted: the response is 409 CONFLICT with details.reason = "active_connections". Disconnect their connections first (Disconnect).