Content API

Create or update a retailer product

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://content.doc.winkelstraat.nl/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "Content API MCP server": {
    "url": "https://content.doc.winkelstraat.nl/mcp"
  }
}
Close
POST /api/rest/v1/retailer/products
Bearer

Purpose: create one product (one size), or update it when a product with this identifier already exists. The product group (parent) is created automatically with the first size. Send one call per size.

Always send the complete product. Every call replaces the product information: the following values are cleared when you leave them out: quantity, special_price, special_price_from_date, special_price_to_date, purchase_price, name, description, season, fit, material and, if an MSRP is agreed with Winkelstraat, msrp and msrp_variation. A missing condition_type is reset to new. price and color cannot be cleared: when you leave them out of an update, they keep their current value and the response is 207, with price or color listed in skipped_attributes. To change one value only, use PATCH /api/rest/v1/retailer/products/{code}/attribute/{attribute_code}.

Required fields

Field Required Expected value
identifier always Your SKU for this size. a-z A-Z 0-9 _ - only.
category always One category code from GET /categories/codes, as a string.
values.manufacturer always Brand code from GET /attributes/manufacturer/options.
values.manufacturer_product_number always The brand's article number.
values.color new product Colour code from GET /attributes/color/options.
values.size new product Size code from GET /attributes/size/options.
values.price new product Selling price in EUR, above 0.
values.quantity new product Stock, a whole number of 0 or higher. With 0 the product is not created (202).
values.ean depends on brand Required when the brand requires an EAN. Must be unique within your products.

Optional fields

Field Expected value
parent Your code for the product group (all sizes of one article in one colour). Generated when left out; we recommend sending it.
enabled Leave it out or send true. false is rejected; use DELETE to stop selling a product.
values.name, values.description Text per language (nl_NL, en_US).
values.msrp Recommended retail price in EUR. Only accepted if agreed with Winkelstraat; then it is cleared when you leave it out of an update.
values.special_price, values.special_price_from_date, values.special_price_to_date Sale price in EUR and the period it applies (dates as YYYY-MM-DD).
values.season, values.condition_type, values.fit, values.material See GET /attributes. condition_type defaults to new.
values.manufacturer_product_color The brand's colour code or name.
values.image_default, values.image_1, … Public image URLs. See the Images topic.

Possible values

Brand, colour, size, season and condition must be codes that Winkelstraat supports. See the Attribute values topic for where to find them.

Responses

  • 201: the product was created. 204: an existing product was updated.
  • 202: a new product was sent with quantity 0 and was not created.
  • 207: the product was saved, but some values were skipped. Usually an update; a create gives 207 when a value does not apply to this kind of product.
  • 409: nothing was saved; retry the same request.
  • 422: nothing was saved; message explains the problem.
application/json

Body Required

  • identifier string Required

    Your SKU for this product (one size). Allowed characters a-z A-Z 0-9 _ -.

  • parent string

    Your code for the product group (all sizes of one article in one colour). Allowed characters a-z A-Z 0-9 _ -. Generated when left out.

  • category string Required

    One category code from GET /api/rest/v1/retailer/categories/codes

  • enabled boolean

    Leave it out or send true. false is rejected.

    Default value is true.

  • values object Required

    Product values per attribute code. See the Attribute values topic and the required fields of the create endpoint.

    Hide values attribute Show values attribute object
    • * array[object] Additional properties
      Hide * attributes Show * attributes object
      • data

        The value. A string, number, boolean, or for prices a list of {amount, currency}.

      • locale string

        nl_NL or en_US for translatable text attributes, otherwise null

      • scope string

        Not used; leave it out or send null

Responses

  • 201

    Created

  • 202

    Accepted, not created

  • 204

    No content

  • 207 application/json

    Multi-Status

    Hide response attributes Show response attributes object
    • code integer

      Always 207

    • message string

      Summary message

    • skipped_attributes array[object]

      Values that were not saved

      Hide skipped_attributes attributes Show skipped_attributes attributes object
      • attribute string

        Attribute code that was skipped

      • value

        The value you sent

      • reason string

        Why the value was skipped
  • 401 application/json

    Authentication required

    Hide response attributes Show response attributes object
    • code integer

      HTTP status code

    • message string

      Message explaining the error
  • 403 application/json

    Access forbidden

    Hide response attributes Show response attributes object
    • code integer

      HTTP status code

    • message string

      Message explaining the error
  • 409 application/json

    Conflict

    Hide response attributes Show response attributes object
    • code integer

      HTTP status code

    • message string

      Message explaining the error
  • 415 application/json

    Unsupported Media type

    Hide response attributes Show response attributes object
    • code integer

      HTTP status code

    • message string

      Message explaining the error
  • 422 application/json

    Unprocessable entity

    Hide response attributes Show response attributes object
    • code integer

      HTTP status code

    • message string

      Message explaining the error
POST /api/rest/v1/retailer/products 
curl \
 --request POST 'https://content.winkelstraat.nl/api/rest/v1/retailer/products' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
  "identifier": "TSHIRT-001-BLACK-M",
  "parent": "TSHIRT-001-BLACK",
  "category": "120",
  "values": {
    "manufacturer": [
      {
        "data": "guess",
        "locale": null
      }
    ],
    "manufacturer_product_number": [
      {
        "data": "G1234",
        "locale": null
      }
    ],
    "manufacturer_product_color": [
      {
        "data": "jet black",
        "locale": null
      }
    ],
    "name": [
      {
        "data": "Basic T-shirt",
        "locale": "en_US"
      },
      {
        "data": "Basic T-shirt",
        "locale": "nl_NL"
      }
    ],
    "description": [
      {
        "data": "Cotton T-shirt with a round neck.",
        "locale": "en_US"
      },
      {
        "data": "Katoenen T-shirt met ronde hals.",
        "locale": "nl_NL"
      }
    ],
    "color": [
      {
        "data": "black",
        "locale": null
      }
    ],
    "size": [
      {
        "data": "m",
        "locale": null
      }
    ],
    "ean": [
      {
        "data": "8712345000028",
        "locale": null
      }
    ],
    "price": [
      {
        "data": [
          {
            "amount": "29.95",
            "currency": "EUR"
          }
        ],
        "locale": null
      }
    ],
    "quantity": [
      {
        "data": 10,
        "locale": null
      }
    ],
    "image_default": [
      {
        "data": "https://cdn.example.com/products/tshirt-001-black-front.jpg",
        "locale": null
      }
    ],
    "image_1": [
      {
        "data": "https://cdn.example.com/products/tshirt-001-black-back.jpg",
        "locale": null
      }
    ]
  }
}'
Request examples 
{
  "identifier": "TSHIRT-001-BLACK-M",
  "parent": "TSHIRT-001-BLACK",
  "category": "120",
  "values": {
    "manufacturer": [
      {
        "data": "guess",
        "locale": null
      }
    ],
    "manufacturer_product_number": [
      {
        "data": "G1234",
        "locale": null
      }
    ],
    "manufacturer_product_color": [
      {
        "data": "jet black",
        "locale": null
      }
    ],
    "name": [
      {
        "data": "Basic T-shirt",
        "locale": "en_US"
      },
      {
        "data": "Basic T-shirt",
        "locale": "nl_NL"
      }
    ],
    "description": [
      {
        "data": "Cotton T-shirt with a round neck.",
        "locale": "en_US"
      },
      {
        "data": "Katoenen T-shirt met ronde hals.",
        "locale": "nl_NL"
      }
    ],
    "color": [
      {
        "data": "black",
        "locale": null
      }
    ],
    "size": [
      {
        "data": "m",
        "locale": null
      }
    ],
    "ean": [
      {
        "data": "8712345000028",
        "locale": null
      }
    ],
    "price": [
      {
        "data": [
          {
            "amount": "29.95",
            "currency": "EUR"
          }
        ],
        "locale": null
      }
    ],
    "quantity": [
      {
        "data": 10,
        "locale": null
      }
    ],
    "image_default": [
      {
        "data": "https://cdn.example.com/products/tshirt-001-black-front.jpg",
        "locale": null
      }
    ],
    "image_1": [
      {
        "data": "https://cdn.example.com/products/tshirt-001-black-back.jpg",
        "locale": null
      }
    ]
  }
}
Response examples (207) 
{
  "code": 207,
  "message": "Product updated with skipped attributes",
  "skipped_attributes": [
    {
      "attribute": "color",
      "value": "darkblue",
      "reason": "The color value darkblue is not supported/disabled"
    },
    {
      "attribute": "size",
      "value": "xxxs",
      "reason": "The size with value 'xxxs' is not supported/disabled"
    }
  ]
}
Response examples (207) 
{
  "code": 42,
  "message": "string",
  "skipped_attributes": [
    {
      "attribute": "string",
      "reason": "string"
    }
  ]
}
Response examples (401) 
{
  "code": 401,
  "message": "The access token provided is invalid."
}
Response examples (401) 
{
  "code": 42,
  "message": "string"
}
Response examples (403) 
{
  "code": 403,
  "message": "Access forbidden. You are not allowed to list products."
}
Response examples (403) 
{
  "code": 42,
  "message": "string"
}
Response examples (409) 
{
  "code": 409,
  "message": "Could not lock \"wsnl123-TSHIRT-001-BLACK\"; the write was not applied and can be retried"
}
Response examples (409) 
{
  "code": 42,
  "message": "string"
}
Response examples (415) 
{
  "code": 415,
  "message": "\"xxx\" in \"Content-Type\" header is not valid. Only \"application/json\" is allowed."
}
Response examples (415) 
{
  "code": 42,
  "message": "string"
}
Response examples (422) 
{
  "code": 422,
  "message": "The color value darkblue is not supported/disabled"
}
Response examples (422) 
{
  "code": 42,
  "message": "string"
}