// api reference

Buyers

GETList buyers, newest first
POSTCreate a buyer
GETRetrieve a buyer
PATCHUpdate a buyer
DELETEErase a buyer's personal data

GET /v1/buyers

List buyers, newest first

secret key only

GET /v1/buyersrequest

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

200 example response, buyer list

{
  "object": "list",
  "data": [
    {
      "object": "buyer",
      "id": "buy_034XtPDs7UJ0TXzTsdaHZa",
      "external_id": "string",
      "display_name": null,
      "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 buyer with this external id.

returns 200, buyer list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of buyer
data[].objectrequired	one of: buyer
data[].idrequired	string
data[].external_idrequired	string
data[].display_namerequired	string or null
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
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/buyers

Create a buyer

secret key only

POST /v1/buyersrequest

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

201 example response, buyer

{
  "object": "buyer",
  "id": "buy_034XtPDs7UJ0TXzTsdaHZa",
  "external_id": "string",
  "display_name": null,
  "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, buyer

fields

Response fields
field	type	about
objectrequired	one of: buyer
idrequired	string
external_idrequired	string
display_namerequired	string or null
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
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/buyers/{id}

Retrieve a buyer

secret key only

GET /v1/buyers/{id}request

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

200 example response, buyer

{
  "object": "buyer",
  "id": "buy_034XtPDs7UJ0TXzTsdaHZa",
  "external_id": "string",
  "display_name": null,
  "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, buyer

fields

Response fields
field	type	about
objectrequired	one of: buyer
idrequired	string
external_idrequired	string
display_namerequired	string or null
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
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/buyers/{id}

Update a buyer

secret key only

PATCH /v1/buyers/{id}request

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

200 example response, buyer

{
  "object": "buyer",
  "id": "buy_034XtPDs7UJ0TXzTsdaHZa",
  "external_id": "string",
  "display_name": null,
  "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, buyer

fields

Response fields
field	type	about
objectrequired	one of: buyer
idrequired	string
external_idrequired	string
display_namerequired	string or null
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
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/buyers/{id}

Erase a buyer's personal data

secret key only

DELETE /v1/buyers/{id}request

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

200 example response, buyer

{
  "object": "buyer",
  "id": "buy_034XtPDs7UJ0TXzTsdaHZa",
  "external_id": "string",
  "display_name": null,
  "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, buyer

fields

Response fields
field	type	about
objectrequired	one of: buyer
idrequired	string
external_idrequired	string
display_namerequired	string or null
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
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.