// api reference

Categories

GETList categories
POSTCreate a category
GETRetrieve a category
PATCHUpdate a category
GETA category's attribute schema
PUTReplace a category's attribute schema

GET /v1/categories

List categories

secret key only

GET /v1/categoriesrequest

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

200 example response, category list

{
  "object": "list",
  "data": [
    {
      "object": "category",
      "id": "cat_034XtPDs7UJ0TXzTsdaHZa",
      "key": "string",
      "name": "string",
      "description": null,
      "parent": null,
      "attribute_schema": {
        "attributes": [
          null
        ]
      },
      "fee": {
        "percent_bps": null,
        "fixed_amount": null
      },
      "prohibited": 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.

returns 200, category list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of category
data[].objectrequired	one of: category
data[].idrequired	string
data[].keyrequired	string
data[].namerequired	string
data[].descriptionrequired	string or null
data[].parentrequired	string or null
data[].attribute_schemarequired	attribute schema
data[].attribute_schema.attributesrequired	array of attribute definition	up to 50 items
data[].feerequired	category fee or null
data[].fee.percent_bps	integer or null	Basis points: 250 is 2.5 percent.min 0, max 10000
data[].fee.fixed_amount	integer or null	Minor units, in the marketplace currency.min 0
data[].prohibitedrequired	boolean	Listings in a prohibited category cannot be published.
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/categories

Create a category

secret key only

POST /v1/categoriesrequest

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

201 example response, category

{
  "object": "category",
  "id": "cat_034XtPDs7UJ0TXzTsdaHZa",
  "key": "string",
  "name": "string",
  "description": null,
  "parent": null,
  "attribute_schema": {
    "attributes": [
      {
        "key": "format",
        "label": "string",
        "type": "string",
        "required": false,
        "options": [
          null
        ],
        "min": 0,
        "max": 0,
        "max_length": 0
      }
    ]
  },
  "fee": {
    "percent_bps": null,
    "fixed_amount": null
  },
  "prohibited": false,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

body, create category

Request body
field	type	about
keyrequired	string	Your key for the category. Unique per marketplace.
namerequired	string	up to 120 characters
description	string or null	up to 2000 characters
parent	string or null	Another category of this marketplace.
attribute_schema	attribute schema
attribute_schema.attributesrequired	array of attribute definition	up to 50 items
attribute_schema.attributes[].keyrequired	string
attribute_schema.attributes[].label	string
attribute_schema.attributes[].typerequired	one of: string, number, integer, boolean, enum
attribute_schema.attributes[].required	boolean
attribute_schema.attributes[].options	array of string
attribute_schema.attributes[].min	integer
attribute_schema.attributes[].max	integer
attribute_schema.attributes[].max_length	integer
fee	category fee or null	Overrides the marketplace's platform fee for listings in this category. Null uses the marketplace fee.
fee.percent_bps	integer or null	Basis points: 250 is 2.5 percent.min 0, max 10000
fee.fixed_amount	integer or null	Minor units, in the marketplace currency.min 0
prohibited	boolean	Listings in a prohibited category cannot be published (section 9.4).default false

returns 201, category

fields

Response fields
field	type	about
objectrequired	one of: category
idrequired	string
keyrequired	string
namerequired	string
descriptionrequired	string or null
parentrequired	string or null
attribute_schemarequired	attribute schema
attribute_schema.attributesrequired	array of attribute definition	up to 50 items
attribute_schema.attributes[].keyrequired	string
attribute_schema.attributes[].label	string
attribute_schema.attributes[].typerequired	one of: string, number, integer, boolean, enum
attribute_schema.attributes[].required	boolean
attribute_schema.attributes[].options	array of string
attribute_schema.attributes[].min	integer
attribute_schema.attributes[].max	integer
attribute_schema.attributes[].max_length	integer
feerequired	category fee or null
fee.percent_bps	integer or null	Basis points: 250 is 2.5 percent.min 0, max 10000
fee.fixed_amount	integer or null	Minor units, in the marketplace currency.min 0
prohibitedrequired	boolean	Listings in a prohibited category cannot be published.
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.

GET /v1/categories/{id}

Retrieve a category

secret key only

GET /v1/categories/{id}request

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

200 example response, category

{
  "object": "category",
  "id": "cat_034XtPDs7UJ0TXzTsdaHZa",
  "key": "string",
  "name": "string",
  "description": null,
  "parent": null,
  "attribute_schema": {
    "attributes": [
      {
        "key": "format",
        "label": "string",
        "type": "string",
        "required": false,
        "options": [
          null
        ],
        "min": 0,
        "max": 0,
        "max_length": 0
      }
    ]
  },
  "fee": {
    "percent_bps": null,
    "fixed_amount": null
  },
  "prohibited": 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, category

fields

Response fields
field	type	about
objectrequired	one of: category
idrequired	string
keyrequired	string
namerequired	string
descriptionrequired	string or null
parentrequired	string or null
attribute_schemarequired	attribute schema
attribute_schema.attributesrequired	array of attribute definition	up to 50 items
attribute_schema.attributes[].keyrequired	string
attribute_schema.attributes[].label	string
attribute_schema.attributes[].typerequired	one of: string, number, integer, boolean, enum
attribute_schema.attributes[].required	boolean
attribute_schema.attributes[].options	array of string
attribute_schema.attributes[].min	integer
attribute_schema.attributes[].max	integer
attribute_schema.attributes[].max_length	integer
feerequired	category fee or null
fee.percent_bps	integer or null	Basis points: 250 is 2.5 percent.min 0, max 10000
fee.fixed_amount	integer or null	Minor units, in the marketplace currency.min 0
prohibitedrequired	boolean	Listings in a prohibited category cannot be published.
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/categories/{id}

Update a category

secret key only

PATCH /v1/categories/{id}request

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

200 example response, category

{
  "object": "category",
  "id": "cat_034XtPDs7UJ0TXzTsdaHZa",
  "key": "string",
  "name": "string",
  "description": null,
  "parent": null,
  "attribute_schema": {
    "attributes": [
      {
        "key": "format",
        "label": "string",
        "type": "string",
        "required": false,
        "options": [
          null
        ],
        "min": 0,
        "max": 0,
        "max_length": 0
      }
    ]
  },
  "fee": {
    "percent_bps": null,
    "fixed_amount": null
  },
  "prohibited": 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 category

Request body
field	type	about
name	string	up to 120 characters
description	string or null
parent	string or null
fee	category fee or null
fee.percent_bps	integer or null	Basis points: 250 is 2.5 percent.min 0, max 10000
fee.fixed_amount	integer or null	Minor units, in the marketplace currency.min 0
prohibited	boolean	Listings in a prohibited category cannot be published. Listings already published stay until moderated.

returns 200, category

fields

Response fields
field	type	about
objectrequired	one of: category
idrequired	string
keyrequired	string
namerequired	string
descriptionrequired	string or null
parentrequired	string or null
attribute_schemarequired	attribute schema
attribute_schema.attributesrequired	array of attribute definition	up to 50 items
attribute_schema.attributes[].keyrequired	string
attribute_schema.attributes[].label	string
attribute_schema.attributes[].typerequired	one of: string, number, integer, boolean, enum
attribute_schema.attributes[].required	boolean
attribute_schema.attributes[].options	array of string
attribute_schema.attributes[].min	integer
attribute_schema.attributes[].max	integer
attribute_schema.attributes[].max_length	integer
feerequired	category fee or null
fee.percent_bps	integer or null	Basis points: 250 is 2.5 percent.min 0, max 10000
fee.fixed_amount	integer or null	Minor units, in the marketplace currency.min 0
prohibitedrequired	boolean	Listings in a prohibited category cannot be published.
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.

GET /v1/categories/{id}/attribute_schema

A category's attribute schema

secret key only

GET /v1/categories/{id}/attribute_schemarequest

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

200 example response, attribute schema

{
  "attributes": [
    {
      "key": "format",
      "label": "string",
      "type": "string",
      "required": false,
      "options": [
        "string"
      ],
      "min": 0,
      "max": 0,
      "max_length": 0
    }
  ]
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, attribute schema

fields

Response fields
field	type	about
attributesrequired	array of attribute definition	up to 50 items
attributes[].keyrequired	string
attributes[].label	string
attributes[].typerequired	one of: string, number, integer, boolean, enum
attributes[].required	boolean
attributes[].options	array of string
attributes[].min	integer
attributes[].max	integer
attributes[].max_length	integer

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/categories/{id}/attribute_schema

Replace a category's attribute schema

Refused if a listing already in the category would no longer fit.

secret key only

PUT /v1/categories/{id}/attribute_schemarequest

curl -X PUT https://api.marketsdk.com/v1/categories/{id}/attribute_schema \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"attributes":[{"key":"format","type":"string"}]}'

200 example response, attribute schema

{
  "attributes": [
    {
      "key": "format",
      "label": "string",
      "type": "string",
      "required": false,
      "options": [
        "string"
      ],
      "min": 0,
      "max": 0,
      "max_length": 0
    }
  ]
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, attribute schema

Request body
field	type	about
attributesrequired	array of attribute definition	up to 50 items
attributes[].keyrequired	string
attributes[].label	string
attributes[].typerequired	one of: string, number, integer, boolean, enum
attributes[].required	boolean
attributes[].options	array of string
attributes[].min	integer
attributes[].max	integer
attributes[].max_length	integer

returns 200, attribute schema

fields

Response fields
field	type	about
attributesrequired	array of attribute definition	up to 50 items
attributes[].keyrequired	string
attributes[].label	string
attributes[].typerequired	one of: string, number, integer, boolean, enum
attributes[].required	boolean
attributes[].options	array of string
attributes[].min	integer
attributes[].max	integer
attributes[].max_length	integer

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.