Update a seller
Changes the name or the externalId of a seller.
Changes a seller of your account. Only the fields you send change. Whatever you leave out stays as it is.
How to send each field
| You send | What happens |
|---|---|
"name": "New name" | Changes the name. |
"name": null | 400 VALIDATION_ERROR: the name can't be empty. |
"externalId": "abc-1" | Changes the externalId. Must be unique in your account. |
"externalId": null | Clears the externalId. |
{} (empty body) | Nothing changes. The response returns the seller as it is. |
metadata is merged key by key, and null removes a key. The rules and examples are in Metadata.
Repeating the same PATCH gives the same result, so there is no Idempotency-Key here.
Common errors
409 CONFLICT: another seller in your account already uses thisexternalId.404 NOT_FOUND: the seller does not exist or belongs to another account.
api_keyAuthorizationBearer <token>API key (mk_...)
id*stringIdentifier of the resource, as returned by the API.
^([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)$uuidapplication/json- body
Fields to change. Only the fields you send are updated.
name?stringNew display name, 1 to 200 characters; leading and trailing spaces are removed. Omit it to keep the current name. null is not accepted.
1 <= length <= 200externalId?|New external identifier, 1 to 120 characters after trimming, unique within your account. Omit it to keep the current value; send null to clear it.
1 <= length <= 120metadata?|Keys to change, merged into the current metadata. A key you send replaces that key's value whole (an object is not merged inside), a key set to null is removed, and the keys you leave out stay as they are. Send metadata: null to remove every key; omit metadata to keep it unchanged. The limits apply to the result of the merge. 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 after the change. With an empty body {} it is returned unchanged.
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 PATCH "https://example.com/v1/sellers/3d1c8a52-7f0e-4b0a-8a65-9c1b2f6d7e01" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Store Ltd" }'{ "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"}