Category attributes

The Marktplaats API supports attributes for both categories and advertisements to specify additional properties of a product like size and color.

Category attributes are recommended attribute names and values for a given category. They help constructing automatic user interfaces in which sellers can select one or more values from a pre-defined list of attributes.

They serve as a basis for the attributes the seller can supply in addition to his own user-defined attributes. You cannot post/put category attributes.

There is a separate url available to get a category attributes.

field	type	constraints	default	Req	W	U
key	string	–		yes	no	no
label	string	–		yes	no	no
labels	object	–		yes	no	no
type	Attribute type	–		yes	no	no
values	array(string)	–		no	no	no
options	array(ValueOption type)	–		no	no	no
minValue	number	applicable to attribute with type NUMBER only		no	no	no
maxValue	number	applicable to attribute with type NUMBER only		no	no	no
minAllowedLength	number	applicable to attribute with type STRING only		no	no	no
maxAllowedLength	number	applicable to attribute with type STRING only		no	no	no
unit	string	applicable to attribute with type NUMBER only		no	no	no
units	object	–		yes	no	no
mandatory	boolean	–		yes	no	no
searchable	boolean	–		yes	no	no
writable	boolean	–		yes	no	no
updateable	boolean	–		yes	no	no
objectAttributeSchemaUrl	string	–		no	no	no

key

Unique name of an attribute.

label

The label of the attribute. Deprecated: Use labels instead.

labels

The localized descriptive names of the attribute, keyed by locale.

type

The label of the attribute

values

A list of all allowed values for the attribute. Deprecated: Use options instead.

options

A list of all allowed values for the attribute.

minValue

Minimum allowed value.

maxValue

Maximum allowed value.

minAllowedLength

Minimum allowed length of user-defined string value.

maxAllowedLength

Maximum allowed length of user-defined string value.

unit

Indicates the unit of a NUMBER attribute. Deprecated: Use units instead.

units

The localized descriptive units of the attribute, keyed by locale.

mandatory

Indicates if attribute is mandatory or can be omitted.

searchable

Indicates if you can filter listing results based on this field.

writable

Indicates if you can set this attribute when creating an advertisement for this category

updateable

Indicates if you can update this attribute for advertisements created in this category

objectAttributeSchemaUrl

URL to retrieve the schema definition for custom object attributes. This endpoint provides the structure and validation rules for complex object-type attributes.

Allowed attribute types

type	description
STRING	User can select a single value from values. Or provide any string if values are not given, between length minAllowedLength and maxAllowedLength.
LIST	User can select one or more values from values.
NUMBER	User can provide an integer number between minValue and maxValue.
DOUBLE	User can provide a floating point number
OBJECT	User can provide a structured object. The schema definition for the object structure is available via objectAttributeSchemaUrl.

Possible value options

A list of all allowed values for the attribute.

field	type	constraints	default	Req	W	U
key	string	–		yes	no	no
labels	object	–		yes	no	no

key

Unique key of a value option.

labels

The localized descriptive labels of the value option, keyed by locale.

Reference

GET /v2/categories/{l1CategoryId}/{l2CategoryId}/attributes

This urls returns attributes for the specified leaf category.

This endpoint will accept either a client access token or a user access token. When this endpoint is called with a client access token, it will return the generic results (ie. not user-specific). But when it is called with a user access token, it will return user-specific results. For example, it may mark some attributes as mandatory if they are mandatory for the corresponding user.

Example

Retrieving category attributes :

Request :

GET /v2/categories/1/2/attributes HTTP/1.1
Host: api.marktplaats.nl

Response :

HTTP/1.1 200 OK
Content-Type: application/json

{
 "_links":{
   "self":{
     "href":"/v2/categories/1/2/attributes"
   },
   "describedby":{
     "href":"https://api.marktplaats.nl/docs/v2/categories.html#attributes"
   }
 },
 "fields": [
      {
          "key": "delivery",
          "label": "Levering",
          "labels": {
              "nl-NL": "Levering"
          },
          "type": "STRING",
          "values": [
              "Ophalen",
              "Verzenden",
              "Ophalen of Verzenden"
          ],
          "options": [
              {
                  "key": "Ophalen",
                  "labels": {
                      "nl-NL": "Ophalen"
                  }
              },
              {
                  "key": "Verzenden",
                  "labels": {
                      "nl-NL": "Verzenden"
                  }
              },
              {
                  "key": "Ophalen of Verzenden",
                  "labels": {
                      "nl-NL": "Ophalen of Verzenden"
                  }
              }
          ],
          "mandatory": false,
          "searchable": true,
          "writable": true,
          "updateable": true
      },
      {
          "key": "properties",
          "label": "Eigenschappen",
          "labels": {
              "nl-NL": "Eigenschappen"
          },
          "type": "LIST",
          "values": [
              "Vering",
              "Opvouwbaar"
          ],
          "options": [
              {
                  "key": "Vering",
                  "labels": {
                      "nl-NL": "Vering"
                  }
              },
              {
                  "key": "Opvouwbaar",
                  "labels": {
                      "nl-NL": "Opvouwbaar"
                  }
              }
          ],
          "mandatory": false,
          "searchable": true,
          "writable": true,
          "updateable": true
      },
      {
          "key": "engineDisplacement",
          "label": "Motorinhoud",
          "labels": {
              "nl-NL": "Motorinhoud"
          },
          "type": "NUMBER",
          "minValue": 1,
          "maxValue": 8500,
          "unit": "cc",
          "units": {
              "nl-NL": "cc"
          },
          "mandatory": false,
          "searchable": true,
          "writable": true,
          "updateable": true
      },
      {
          "key": "manufacturerEmail",
          "label": "E-mailadres fabrikant",
          "labels": {
              "nl-NL": "E-mailadres fabrikant"
          },
          "type": "STRING",
          "minAllowedLength": 0,
          "maxAllowedLength": 64,
          "mandatory": true,
          "searchable": false,
          "writable": true,
          "updateable": true
      }]
  }

GET /v2/categories/objectAttributeDefinitions/{attributeName}

This endpoint returns the schema definition for custom object attributes. It provides the structure, validation rules, and allowed properties for object-type category attributes.

The attributeName parameter should match the key value of an attribute with type OBJECT. This endpoint is referenced by the objectAttributeSchemaUrl field in category attributes.

This endpoint accepts either a client access token or a user access token.

Example

Retrieving object attribute definitions : This endpoint provides JSON Schema definitions for object attributes. The example below shows the schema for service-packages. For the most up-to-date schema definition, always call the API endpoint directly.

Request :

GET /v2/categories/objectAttributeDefinitions/service-packages HTTP/1.1
Host: api.marktplaats.nl

Response :

HTTP/1.1 200 OK
Content-Type: application/schema+json

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "service-packages",
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "title": {
                "type": "string",
                "minLength": 1,
                "description": "Title of the service package"
            },
            "price": {
                "type": "integer",
                "description": "Value in cents. 0 is allowed if the service package is included in the asking price of the item.",
                "minimum": 0
            },
            "content": {
                "type": "array",
                "description": "List of bullet points included in the service package",
                "items": {
                    "type": "string",
                    "minLength": 1
                }
            },
            "locale": {
                "type": "string",
                "enum": [
                    "nl-NL"
                ]
            }
        }
    }
}