Create a seller
Registers a merchant in your account.
Creates a seller. Call it when a new customer joins your platform. The response carries the seller's id, which you use in the other endpoints.
If you'd rather not store our id, send your customer's id in your system as externalId. It must be unique within your account.
To store your own data on the seller, use metadata. See Metadata.
Every seller is born with a default warehouse, created in the same operation. So, right after seller.created, a warehouse.created arrives too.
Retry without duplicates
Networks fail. Send an Idempotency-Key (a UUID works) and, if the response doesn't arrive, repeat the request with the same key and the same body. You get the original response, with the header Idempotency-Replayed: true, and no new seller is created. The key is valid for 24 hours. Details in Idempotency and limits.
Common errors
409 CONFLICTwithdetails.field = "externalId": a seller with thisexternalIdalready exists in your account.409 CONFLICTwithoutdetails: theIdempotency-Keywas already used with a different body. Generate a new key for a new request.400 VALIDATION_ERROR: invalid body, for example an emptyname.detailslists each field with a problem.
api_keyAuthorizationBearer <token>API key (mk_...)
Idempotency-Key?stringOptional. 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.
1 <= length <= 255application/json- body
name*stringDisplay name of the seller. Required, 1 to 200 characters; leading and trailing spaces are removed.
1 <= length <= 200externalId?|Optional. Your own identifier for this seller, 1 to 120 characters after trimming. Must be unique within your account (another account may reuse it). Accepts null.
1 <= length <= 120metadata?|Optional. Your own key-value data for this seller, to keep what you need and filter the listing by it later (GET /v1/sellers?metadata[key]=value). A value can be any JSON: string, number, boolean, array or object. A top-level key whose value is null is not stored; metadata: null or no metadata gives {}. Up to 50 top-level keys of 1 to 40 characters (letters, digits, _ and -; __proto__ is reserved); keys inside nested objects are free. Up to 8192 bytes as compact JSON and up to 5 levels of nesting ({"a":1} is 1 level, {"a":{"b":1}} is 2, and an array counts as a level). Numbers must fit JSON, and text cannot contain the NUL character (\u0000).
The seller was created. The body is the new seller.
application/json- response
A seller: your customer, who connects marketplaces through you.
id*stringOpaque unique identifier of the seller, generated by the API. Use it in the /v1/sellers/{id} routes.
^([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)$uuidname*stringDisplay name of the seller.
externalId*|Your own identifier for this seller, so you can find the record without storing ours. null when it was never set. Unique within your account.
metadata*Your own key-value data for this seller, as stored: top-level keys sent as null are not kept, and key order is not preserved. {} when there is none. Filter the listing by it with metadata[key]=value.
connections*array<>The marketplace accounts this seller has connected and working (status: active), newest first. Empty when there is none. For the full records, or other states, call GET /v1/connections with Seller-Id.
createdAt*stringWhen the seller was created, in ISO-8601 (UTC).
^(?:(?:\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))$date-timeupdatedAt*stringWhen the seller was last changed, in ISO-8601 (UTC).
^(?:(?:\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))$date-timecurl -X POST "https://example.com/v1/sellers" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Store", "externalId": "customer-123", "metadata": { "plan": "pro", "region": "south", "tags": [ "vip", "b2b" ] } }'{ "id": "3d1c8a52-7f0e-4b0a-8a65-9c1b2f6d7e01", "name": "Acme Store", "externalId": "customer-123", "metadata": { "plan": "pro", "region": "south", "tags": [ "vip", "b2b" ] }, "connections": [ { "id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "marketplace": "mercadolivre", "marketplaceDisplayName": "Mercado Livre", "status": "active" } ], "createdAt": "2026-10-06T14:30:00.000Z", "updatedAt": "2026-10-06T14:30:00.000Z"}