// api reference

Sellers

GETList sellers, newest first
POSTCreate a seller
GETRetrieve a seller
PATCHUpdate a seller
DELETEErase a seller's personal data
PUTCreate or replace a seller's storefront
POSTCreate a Stripe onboarding link for a seller
GETA seller's public profile

GET /v1/sellers

List sellers, newest first

secret key only

GET /v1/sellersrequest

curl https://api.marketsdk.com/v1/sellers \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, seller list

{
  "object": "list",
  "data": [
    {
      "object": "seller",
      "id": "sel_034XtPDs7UJ0TXzTsdaHZa",
      "external_id": "string",
      "display_name": null,
      "status": "active",
      "suspended_reason": null,
      "verification": {
        "status": "unverified",
        "verified_at": null
      },
      "payouts": {
        "status": "not_started",
        "requirements_due": [
          null
        ],
        "stripe_account": null
      },
      "storefront": {
        "object": "storefront",
        "name": "string",
        "slug": "string",
        "description": null,
        "metadata": {},
        "updated_at": "2026-10-01T12:00:00.000Z"
      },
      "reputation": {
        "completed_orders": 0,
        "backed_out": 0,
        "disputes_lost": 0,
        "review_count": 0,
        "average_rating": null,
        "score": null,
        "level": "new"
      },
      "metadata": {},
      "erased": false,
      "created_at": "2026-10-01T12:00:00.000Z",
      "updated_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

parameters

Parameters
field	type	about
limit	integer, in query	min 1, max 100, default 20
starting_after	string, in query	The `next_cursor` of the previous page.
external_id	string, in query	Find the seller with this external id.
status	one of: active, suspended, in query

returns 200, seller list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of seller
data[].objectrequired	one of: seller
data[].idrequired	string
data[].external_idrequired	string
data[].display_namerequired	string or null
data[].statusrequired	one of: active, suspended
data[].suspended_reasonrequired	string or null
data[].verificationrequired	seller verification summary
data[].verification.statusrequired	one of: unverified, pending, verified, requires_input, canceled	From the latest identity verification. Once verified, a seller stays verified.
data[].verification.verified_atrequired	timestamp or null
data[].payoutsrequired	seller payouts
data[].payouts.statusrequired	one of: not_started, pending, enabled, restricted	`not_started` before the first onboarding link; `pending` while Stripe onboarding is unfinished or under review; `enabled` when the seller can receive transfers; `restricted` when Stripe needs more from the seller.
data[].payouts.requirements_duerequired	array of string	What Stripe still needs from the seller, by Stripe's field names. Send a new onboarding link to collect it.
data[].payouts.stripe_accountrequired	string or null	The seller's connected account on your Stripe account.
data[].storefrontrequired	storefront or null
data[].storefront.objectrequired	one of: storefront
data[].storefront.namerequired	string
data[].storefront.slugrequired	string
data[].storefront.descriptionrequired	string or null
data[].storefront.metadatarequired	object of strings
data[].storefront.updated_atrequired	timestamp
data[].reputationrequired	reputation
data[].reputation.completed_ordersrequired	integer	order_completed events in the rolling window.
data[].reputation.backed_outrequired	integer	backed_out events in the rolling window.
data[].reputation.disputes_lostrequired	integer	dispute_lost events in the rolling window.
data[].reputation.review_countrequired	integer	Visible reviews in the rolling window.
data[].reputation.average_ratingrequired	integer or null	Plain mean of those ratings, or null.
data[].reputation.scorerequired	integer or null	Null until the minimum number of events.min 0, max 100
data[].reputation.levelrequired	one of: new, low, fair, good, excellent
data[].metadatarequired	object of strings
data[].erasedrequired	boolean	True once the seller's personal data has been erased at your request.
data[].created_atrequired	timestamp
data[].updated_atrequired	timestamp
has_morerequired	boolean	Whether another page follows.
next_cursorrequired	string or null	Pass as `starting_after` (or `cursor` for search) to get the next page.

errors

400The request is not valid.
401No API key, or not a valid one.
429Rate limited. See Retry-After.

POST /v1/sellers

Create a seller

secret key only

POST /v1/sellersrequest

curl -X POST https://api.marketsdk.com/v1/sellers \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"external_id":"string"}'

201 example response, seller

{
  "object": "seller",
  "id": "sel_034XtPDs7UJ0TXzTsdaHZa",
  "external_id": "string",
  "display_name": null,
  "status": "active",
  "suspended_reason": null,
  "verification": {
    "status": "unverified",
    "verified_at": null
  },
  "payouts": {
    "status": "not_started",
    "requirements_due": [
      "string"
    ],
    "stripe_account": null
  },
  "storefront": {
    "object": "storefront",
    "name": "string",
    "slug": "string",
    "description": null,
    "metadata": {},
    "updated_at": "2026-10-01T12:00:00.000Z"
  },
  "reputation": {
    "completed_orders": 0,
    "backed_out": 0,
    "disputes_lost": 0,
    "review_count": 0,
    "average_rating": null,
    "score": null,
    "level": "new"
  },
  "metadata": {},
  "erased": false,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

body, create party

Request body
field	type	about
external_idrequired	string	Your own id for this person. Unique per marketplace.up to 200 characters
display_name	string	up to 200 characters
metadata	object of strings

returns 201, seller

fields

Response fields
field	type	about
objectrequired	one of: seller
idrequired	string
external_idrequired	string
display_namerequired	string or null
statusrequired	one of: active, suspended
suspended_reasonrequired	string or null
verificationrequired	seller verification summary
verification.statusrequired	one of: unverified, pending, verified, requires_input, canceled	From the latest identity verification. Once verified, a seller stays verified.
verification.verified_atrequired	timestamp or null
payoutsrequired	seller payouts
payouts.statusrequired	one of: not_started, pending, enabled, restricted	`not_started` before the first onboarding link; `pending` while Stripe onboarding is unfinished or under review; `enabled` when the seller can receive transfers; `restricted` when Stripe needs more from the seller.
payouts.requirements_duerequired	array of string	What Stripe still needs from the seller, by Stripe's field names. Send a new onboarding link to collect it.
payouts.stripe_accountrequired	string or null	The seller's connected account on your Stripe account.
storefrontrequired	storefront or null
storefront.objectrequired	one of: storefront
storefront.namerequired	string
storefront.slugrequired	string
storefront.descriptionrequired	string or null
storefront.metadatarequired	object of strings
storefront.updated_atrequired	timestamp
reputationrequired	reputation
reputation.completed_ordersrequired	integer	order_completed events in the rolling window.
reputation.backed_outrequired	integer	backed_out events in the rolling window.
reputation.disputes_lostrequired	integer	dispute_lost events in the rolling window.
reputation.review_countrequired	integer	Visible reviews in the rolling window.
reputation.average_ratingrequired	integer or null	Plain mean of those ratings, or null.
reputation.scorerequired	integer or null	Null until the minimum number of events.min 0, max 100
reputation.levelrequired	one of: new, low, fair, good, excellent
metadatarequired	object of strings
erasedrequired	boolean	True once the seller's personal data has been erased at your request.
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

GET /v1/sellers/{id}

Retrieve a seller

secret key only

GET /v1/sellers/{id}request

curl https://api.marketsdk.com/v1/sellers/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, seller

{
  "object": "seller",
  "id": "sel_034XtPDs7UJ0TXzTsdaHZa",
  "external_id": "string",
  "display_name": null,
  "status": "active",
  "suspended_reason": null,
  "verification": {
    "status": "unverified",
    "verified_at": null
  },
  "payouts": {
    "status": "not_started",
    "requirements_due": [
      "string"
    ],
    "stripe_account": null
  },
  "storefront": {
    "object": "storefront",
    "name": "string",
    "slug": "string",
    "description": null,
    "metadata": {},
    "updated_at": "2026-10-01T12:00:00.000Z"
  },
  "reputation": {
    "completed_orders": 0,
    "backed_out": 0,
    "disputes_lost": 0,
    "review_count": 0,
    "average_rating": null,
    "score": null,
    "level": "new"
  },
  "metadata": {},
  "erased": false,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, seller

fields

Response fields
field	type	about
objectrequired	one of: seller
idrequired	string
external_idrequired	string
display_namerequired	string or null
statusrequired	one of: active, suspended
suspended_reasonrequired	string or null
verificationrequired	seller verification summary
verification.statusrequired	one of: unverified, pending, verified, requires_input, canceled	From the latest identity verification. Once verified, a seller stays verified.
verification.verified_atrequired	timestamp or null
payoutsrequired	seller payouts
payouts.statusrequired	one of: not_started, pending, enabled, restricted	`not_started` before the first onboarding link; `pending` while Stripe onboarding is unfinished or under review; `enabled` when the seller can receive transfers; `restricted` when Stripe needs more from the seller.
payouts.requirements_duerequired	array of string	What Stripe still needs from the seller, by Stripe's field names. Send a new onboarding link to collect it.
payouts.stripe_accountrequired	string or null	The seller's connected account on your Stripe account.
storefrontrequired	storefront or null
storefront.objectrequired	one of: storefront
storefront.namerequired	string
storefront.slugrequired	string
storefront.descriptionrequired	string or null
storefront.metadatarequired	object of strings
storefront.updated_atrequired	timestamp
reputationrequired	reputation
reputation.completed_ordersrequired	integer	order_completed events in the rolling window.
reputation.backed_outrequired	integer	backed_out events in the rolling window.
reputation.disputes_lostrequired	integer	dispute_lost events in the rolling window.
reputation.review_countrequired	integer	Visible reviews in the rolling window.
reputation.average_ratingrequired	integer or null	Plain mean of those ratings, or null.
reputation.scorerequired	integer or null	Null until the minimum number of events.min 0, max 100
reputation.levelrequired	one of: new, low, fair, good, excellent
metadatarequired	object of strings
erasedrequired	boolean	True once the seller's personal data has been erased at your request.
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

PATCH /v1/sellers/{id}

Update a seller

secret key only

PATCH /v1/sellers/{id}request

curl -X PATCH https://api.marketsdk.com/v1/sellers/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

200 example response, seller

{
  "object": "seller",
  "id": "sel_034XtPDs7UJ0TXzTsdaHZa",
  "external_id": "string",
  "display_name": null,
  "status": "active",
  "suspended_reason": null,
  "verification": {
    "status": "unverified",
    "verified_at": null
  },
  "payouts": {
    "status": "not_started",
    "requirements_due": [
      "string"
    ],
    "stripe_account": null
  },
  "storefront": {
    "object": "storefront",
    "name": "string",
    "slug": "string",
    "description": null,
    "metadata": {},
    "updated_at": "2026-10-01T12:00:00.000Z"
  },
  "reputation": {
    "completed_orders": 0,
    "backed_out": 0,
    "disputes_lost": 0,
    "review_count": 0,
    "average_rating": null,
    "score": null,
    "level": "new"
  },
  "metadata": {},
  "erased": false,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, update party

Request body
field	type	about
display_name	string or null	up to 200 characters
metadata	object of strings

returns 200, seller

fields

Response fields
field	type	about
objectrequired	one of: seller
idrequired	string
external_idrequired	string
display_namerequired	string or null
statusrequired	one of: active, suspended
suspended_reasonrequired	string or null
verificationrequired	seller verification summary
verification.statusrequired	one of: unverified, pending, verified, requires_input, canceled	From the latest identity verification. Once verified, a seller stays verified.
verification.verified_atrequired	timestamp or null
payoutsrequired	seller payouts
payouts.statusrequired	one of: not_started, pending, enabled, restricted	`not_started` before the first onboarding link; `pending` while Stripe onboarding is unfinished or under review; `enabled` when the seller can receive transfers; `restricted` when Stripe needs more from the seller.
payouts.requirements_duerequired	array of string	What Stripe still needs from the seller, by Stripe's field names. Send a new onboarding link to collect it.
payouts.stripe_accountrequired	string or null	The seller's connected account on your Stripe account.
storefrontrequired	storefront or null
storefront.objectrequired	one of: storefront
storefront.namerequired	string
storefront.slugrequired	string
storefront.descriptionrequired	string or null
storefront.metadatarequired	object of strings
storefront.updated_atrequired	timestamp
reputationrequired	reputation
reputation.completed_ordersrequired	integer	order_completed events in the rolling window.
reputation.backed_outrequired	integer	backed_out events in the rolling window.
reputation.disputes_lostrequired	integer	dispute_lost events in the rolling window.
reputation.review_countrequired	integer	Visible reviews in the rolling window.
reputation.average_ratingrequired	integer or null	Plain mean of those ratings, or null.
reputation.scorerequired	integer or null	Null until the minimum number of events.min 0, max 100
reputation.levelrequired	one of: new, low, fair, good, excellent
metadatarequired	object of strings
erasedrequired	boolean	True once the seller's personal data has been erased at your request.
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

DELETE /v1/sellers/{id}

Erase a seller's personal data

Removes the name, external id, metadata, storefront, and review text, and takes the listings down. Orders and reputation stay, without personal data.

secret key only

DELETE /v1/sellers/{id}request

curl -X DELETE https://api.marketsdk.com/v1/sellers/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, seller

{
  "object": "seller",
  "id": "sel_034XtPDs7UJ0TXzTsdaHZa",
  "external_id": "string",
  "display_name": null,
  "status": "active",
  "suspended_reason": null,
  "verification": {
    "status": "unverified",
    "verified_at": null
  },
  "payouts": {
    "status": "not_started",
    "requirements_due": [
      "string"
    ],
    "stripe_account": null
  },
  "storefront": {
    "object": "storefront",
    "name": "string",
    "slug": "string",
    "description": null,
    "metadata": {},
    "updated_at": "2026-10-01T12:00:00.000Z"
  },
  "reputation": {
    "completed_orders": 0,
    "backed_out": 0,
    "disputes_lost": 0,
    "review_count": 0,
    "average_rating": null,
    "score": null,
    "level": "new"
  },
  "metadata": {},
  "erased": false,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, seller

fields

Response fields
field	type	about
objectrequired	one of: seller
idrequired	string
external_idrequired	string
display_namerequired	string or null
statusrequired	one of: active, suspended
suspended_reasonrequired	string or null
verificationrequired	seller verification summary
verification.statusrequired	one of: unverified, pending, verified, requires_input, canceled	From the latest identity verification. Once verified, a seller stays verified.
verification.verified_atrequired	timestamp or null
payoutsrequired	seller payouts
payouts.statusrequired	one of: not_started, pending, enabled, restricted	`not_started` before the first onboarding link; `pending` while Stripe onboarding is unfinished or under review; `enabled` when the seller can receive transfers; `restricted` when Stripe needs more from the seller.
payouts.requirements_duerequired	array of string	What Stripe still needs from the seller, by Stripe's field names. Send a new onboarding link to collect it.
payouts.stripe_accountrequired	string or null	The seller's connected account on your Stripe account.
storefrontrequired	storefront or null
storefront.objectrequired	one of: storefront
storefront.namerequired	string
storefront.slugrequired	string
storefront.descriptionrequired	string or null
storefront.metadatarequired	object of strings
storefront.updated_atrequired	timestamp
reputationrequired	reputation
reputation.completed_ordersrequired	integer	order_completed events in the rolling window.
reputation.backed_outrequired	integer	backed_out events in the rolling window.
reputation.disputes_lostrequired	integer	dispute_lost events in the rolling window.
reputation.review_countrequired	integer	Visible reviews in the rolling window.
reputation.average_ratingrequired	integer or null	Plain mean of those ratings, or null.
reputation.scorerequired	integer or null	Null until the minimum number of events.min 0, max 100
reputation.levelrequired	one of: new, low, fair, good, excellent
metadatarequired	object of strings
erasedrequired	boolean	True once the seller's personal data has been erased at your request.
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

PUT /v1/sellers/{id}/storefront

Create or replace a seller's storefront

secret key only

PUT /v1/sellers/{id}/storefrontrequest

curl -X PUT https://api.marketsdk.com/v1/sellers/{id}/storefront \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","slug":"jane-templates"}'

200 example response, storefront

{
  "object": "storefront",
  "name": "string",
  "slug": "string",
  "description": null,
  "metadata": {},
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, storefront

Request body
field	type	about
namerequired	string	up to 120 characters
slugrequired	string	Lowercase letters, digits, and hyphens. Unique per marketplace.
description	string or null	up to 5000 characters
metadata	object of strings

returns 200, storefront

fields

Response fields
field	type	about
objectrequired	one of: storefront
namerequired	string
slugrequired	string
descriptionrequired	string or null
metadatarequired	object of strings
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

POST /v1/sellers/{id}/onboarding_links

Create a Stripe onboarding link for a seller

The first link creates the seller's connected account on your Stripe account: Express, with Stripe collecting what the law requires, your platform paying Stripe's fees and bearing losses, and only transfers requested. Send the seller to the link; their payouts status follows as Stripe reports it.

secret key only

POST /v1/sellers/{id}/onboarding_linksrequest

curl -X POST https://api.marketsdk.com/v1/sellers/{id}/onboarding_links \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"return_url":"string","refresh_url":"string"}'

201 example response, onboarding link

{
  "object": "onboarding_link",
  "seller": "string",
  "url": "string",
  "expires_at": "2026-10-01T12:00:00.000Z",
  "payouts": {
    "status": "not_started",
    "requirements_due": [
      "string"
    ],
    "stripe_account": null
  }
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, onboarding link

Request body
field	type	about
return_urlrequired	string	Where Stripe sends the seller when they finish or leave onboarding.
refresh_urlrequired	string	Where Stripe sends the seller if the link expired. Create a new link there.
country	string	The seller's country, two letters. Used only when the seller's Stripe account is created, on the first link. Defaults to your Stripe account's country.

returns 201, onboarding link

fields

Response fields
field	type	about
objectrequired	one of: onboarding_link
sellerrequired	string
urlrequired	string	Stripe-hosted onboarding, carrying your branding. Single use, and short-lived.
expires_atrequired	timestamp
payoutsrequired	seller payouts
payouts.statusrequired	one of: not_started, pending, enabled, restricted	`not_started` before the first onboarding link; `pending` while Stripe onboarding is unfinished or under review; `enabled` when the seller can receive transfers; `restricted` when Stripe needs more from the seller.
payouts.requirements_duerequired	array of string	What Stripe still needs from the seller, by Stripe's field names. Send a new onboarding link to collect it.
payouts.stripe_accountrequired	string or null	The seller's connected account on your Stripe account.

errors

400The request is not valid.
401No API key, or not a valid one.
403Not allowed with this key, or the marketplace is read-only.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

GET /v1/sellers/{id}/profile

A seller's public profile

Callable with a publishable key. Shows only what a buyer may see.

secret key, or a publishable key from a browser

GET /v1/sellers/{id}/profilerequest

curl https://api.marketsdk.com/v1/sellers/{id}/profile \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, seller profile

{
  "object": "seller_profile",
  "id": "string",
  "display_name": null,
  "verification_status": "unverified",
  "storefront": {
    "object": "storefront",
    "name": "string",
    "slug": "string",
    "description": null,
    "metadata": {},
    "updated_at": "2026-10-01T12:00:00.000Z"
  },
  "reputation": {
    "completed_orders": 0,
    "backed_out": 0,
    "disputes_lost": 0,
    "review_count": 0,
    "average_rating": null,
    "score": null,
    "level": "new"
  }
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, seller profile

fields

Response fields
field	type	about
objectrequired	one of: seller_profile
idrequired	string
display_namerequired	string or null
verification_statusrequired	one of: unverified, pending, verified, requires_input, canceled
storefrontrequired	storefront or null
storefront.objectrequired	one of: storefront
storefront.namerequired	string
storefront.slugrequired	string
storefront.descriptionrequired	string or null
storefront.metadatarequired	object of strings
storefront.updated_atrequired	timestamp
reputationrequired	reputation
reputation.completed_ordersrequired	integer	order_completed events in the rolling window.
reputation.backed_outrequired	integer	backed_out events in the rolling window.
reputation.disputes_lostrequired	integer	dispute_lost events in the rolling window.
reputation.review_countrequired	integer	Visible reviews in the rolling window.
reputation.average_ratingrequired	integer or null	Plain mean of those ratings, or null.
reputation.scorerequired	integer or null	Null until the minimum number of events.min 0, max 100
reputation.levelrequired	one of: new, low, fair, good, excellent

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.