Rest API

The Marketplace Seller API by Kaufland is an HTTP interface to the Kaufland marketplace. It allows you to search the site, retrieve information about products, and manage your own inventory and sales. This page provides a general overview of the Marketplace Seller API and the endpoints documentation page provides detailed information about each of the available API endpoints.

Overview

The Marketplace Seller API uses a Representational state transfer (REST) interface and uses a simple password and HMAC based authentication method.
The Marketplace Seller API allows you to query the Kaufland marketplace. For example, you can search the site for products or categories. It also enables you to manage your own account data. For example, you can add new units you are offering for sale or get reports about your recent sales.
All Marketplace Seller API requests must be authenticated and signed with the keys from your seller account. There is no anonymous access to the Marketplace Seller API.

Requirements

Before you start make sure that you have both a Client Key (a 32 character string) and Secret Key (a 64 character string). If you have not already received these keys from Kaufland marketplace, or you have lost your keys, you can generate new ones on your API settings page.

Examples:

Client Key: 7bffc16ba2cc5ac1cbf527d6fa39263

Secret Key: a7d0cb1da1ddbc86c96ee5fedd341b7d8ebfbb2f5c83cfe0909f4e57f05dd403

Warning: Do not lose your API keys. For security, they cannot be retrieved if they are lost. If you lose them, you will have to generate new ones on your API settings page.

Sending Requests

General Information

In order to interact with the API, you must send an HTTPS (SSL encrypted) request to one of the available API endpoints. All requests must contain several HTTP headers (see below). Some of the API actions require use of the PATCH or POST verbs, and the body of those requests must be in a valid JSON format.

Required Headers

Each request must contain 5 headers:

Accept - All requests must contain an Accept header set to application/json.
Shop-Client-Key - All requests must contain an Shop-Client-Key header with the value of your Client Key.
Shop-Timestamp - All requests must contain an Shop-Timestamp header with the current Unix Timestamp in seconds and must be current at the time the request is made. There is a 10-minute window around the current time to account for clock skew. In other words, your timestamp can be up to 5 minutes earlier or 5 minutes later than the current server time. If the timestamp is more than 5 minutes different from the current server time when the request is received, the request will be rejected.
Shop-Signature - All requests must contain an Shop-Signature header which contains an HMAC signature of the request. The HMAC is specific to each request, so it must be regenerated for each request.
User-Agent - All requests must include a User-Agent header containing either the name of your software solution if you are a software provider, or the term "Inhouse_development" if it is your individual and customized connection.
POST/PATCH requests will need the Content-Type header with the value application/json.

Signing Requests

Each request must be signed by a SHA-256 HMAC in base64 encoding. This HMAC is generated by concatenating the request information together, separated by newline characters, and generating a SHA-256 HMAC from the resulting string and your Secret Key.

Here is an implementation of the HMAC generation function in PHP:

function signRequest($method, $uri, $body, $timestamp, $secretKey)
{
	$string = implode("\n", [
		$method,
		$uri,
		$body,
		$timestamp,
	]);

	return hash_hmac('sha256', $string, $secretKey);
}

The required values in the signature string are:

$method - The HTTP method of the request, uppercased (e.g. GET, POST, PATCH, DELETE).
$uri - The full URI of the request, including https:// and the full domain name (e.g. https://sellerapi.kaufland.com/v2/units/).
$body - The body of the request. If request doesn't contain a body, the empty string should be used.
$timestamp - The value of the current Unix timestamp at the time of the request. This must be the same as the value of the Shop-Timestamp header.
$secretKey - Your Secret Key, which you received from the Kaufland marketplace.

The PHP function hash_hmac() produces an HMAC using SHA-256 as the cryptographic hash function.

For example, you could generate an HMAC for the following values (again, in PHP):

$method = "POST";
$uri = "https://sellerapi.kaufland.com/v2/units/";
$body = "";
$timestamp = 1411055926;
$secretKey = "a7d0cb1da1ddbc86c96ee5fedd341b7d8ebfbb2f5c83cfe0909f4e57f05dd403";

The correct Shop-Signature generated by these values is:
da0b65f51c0716c1d3fa658b7eaf710583630a762a98c9af8e9b392bd9df2e2a.

Here is the same function written in several different languages, along with a full test program:

Signature function

function signRequest($method, $uri, $body, $timestamp, $secretKey)
{
	$string = implode("\n", [
		$method,
		$uri,
		$body,
		$timestamp,
	]);

	return hash_hmac('sha256', $string, $secretKey);
}

Full example


<?php

$method = "POST";
$uri = "https://sellerapi.kaufland.com/v2/units/";
$body = "";
$timestamp = 1411055926; //time();
$secretKey = "a7d0cb1da1ddbc86c96ee5fedd341b7d8ebfbb2f5c83cfe0909f4e57f05dd403";

$hmac = signRequest($method, $uri, $body, $timestamp, $secretKey);
print("\n$hmac\n"); // da0b65f51c0716c1d3fa658b7eaf710583630a762a98c9af8e9b392bd9df2e2a

function signRequest($method, $uri, $body, $timestamp, $secretKey)
{
	$string = implode("\n", [
		$method,
		$uri,
		$body,
		$timestamp,
	]);

	return hash_hmac('sha256', $string, $secretKey);
}

Signature function


import hmac
import hashlib

def sign_request(method, uri, body, timestamp, secret_key):
	plain_text = "\n".join([method, uri, body, str(timestamp)])

	digest_maker = hmac.new(secret_key.encode(), None, hashlib.sha256)
	digest_maker.update(plain_text.encode())
	return digest_maker.hexdigest()

Full example


#!/usr/bin/python

import hmac
import hashlib
import time

def sign_request(method, uri, body, timestamp, secret_key):
    plain_text = "\n".join([method, uri, body, str(timestamp)])

    digest_maker = hmac.new(secret_key.encode(), None, hashlib.sha256)
    digest_maker.update(plain_text.encode())
    return digest_maker.hexdigest()

method = "POST"
uri = "https://sellerapi.kaufland.com/v2/units/"
body = ""
timestamp = 1411055926 # time.time()
secret_key = "a7d0cb1da1ddbc86c96ee5fedd341b7d8ebfbb2f5c83cfe0909f4e57f05dd403"

print(sign_request(method, uri, body, timestamp, secret_key))
# da0b65f51c0716c1d3fa658b7eaf710583630a762a98c9af8e9b392bd9df2e2a

Signature function


import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;
import java.security.NoSuchAlgorithmException;
import java.security.InvalidKeyException;

public static String signRequest(String method, String uri, String body, long timestamp, String secretKey)
	throws NoSuchAlgorithmException, InvalidKeyException {

	String plainText = method + "\n" + uri + "\n" + body + "\n" + timestamp;

	Mac mac = Mac.getInstance("HmacSHA256");
	SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
	mac.init(secretKeySpec);

	byte[] rawHmac = mac.doFinal(plainText.getBytes());
	return DatatypeConverter.printHexBinary(rawHmac);
}

Full example


import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;
import java.security.NoSuchAlgorithmException;
import java.security.InvalidKeyException;

public class Hmac {

	public static void main(String[] args) {
		String method = "POST";
		String uri = "https://sellerapi.kaufland.com/v2/units/";
		String body = "";
		String secretKey = "a7d0cb1da1ddbc86c96ee5fedd341b7d8ebfbb2f5c83cfe0909f4e57f05dd403";
		long timestamp = 1411055926; // System.currentTimeMillis() / 1000L;

		try {
			String signature = signRequest(method, uri, body, timestamp, secretKey);
			System.out.println(signature); // da0b65f51c0716c1d3fa658b7eaf710583630a762a98c9af8e9b392bd9df2e2a
		} catch (Exception e) {
			System.out.println("Error signing request");
		}
	}

	public static String signRequest(String method, String uri, String body, long timestamp, String secretKey)
		throws NoSuchAlgorithmException, InvalidKeyException {

		String plainText = method + "\n" + uri + "\n" + body + "\n" + timestamp;

		Mac mac = Mac.getInstance("HmacSHA256");
		SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
		mac.init(secretKeySpec);

		byte[] rawHmac = mac.doFinal(plainText.getBytes());
		return DatatypeConverter.printHexBinary(rawHmac);
	}
}

Note that the Secret Key is always a string that just happens to look like a hexadecimal number. Do not interpret it as a hex value, or you will generate the wrong signature!

Reading Responses

Responses from the Marketplace Seller API can either have an empty body or contain a UTF-8 encoded JSON string in the body. Only GET operations respond with a non-empty body. When a body is sent, the Content-Type of the response will be application/json.

JSON responses may have one of two formats:

Object - represents a single model entity, e.g. a product, or an order. The corresponding javascript type of the root-level element is object.
Collection - represents a set of Objects of the same type. The corresponding javascript type of the root-level element is array.

An example of an Object response:

{
	"data": {
		"id_category": 21,
		"name": "parfuem",
		"id_parent_category": 11,
		"title_singular": "Parfüm",
		"title_plural": "Parfüms",
		"level": 2,
		"url": "https://www.kaufland.de/parfuem/",
		"shipping_category": "D",
		"variable_fee": "8.50",
		"fixed_fee": 0,
		"vat": "19.00",
		"parent": {
			"id_category": 11,
			"name": "koerperpflege-und-gesundheit",
			"id_parent_category": 1,
			"title_singular": "Körperpflege & Gesundheit",
			"title_plural": "Körperpflege & Gesundheit",
			"level": 1,
			"url": "https://www.kaufland.de/koerperpflege-und-gesundheit/",
			"shipping_category": "D",
			"variable_fee": "12.50",
			"fixed_fee": 0,
			"vat": "19.00"
		}
	}
}

An example of a Collection response:

{
	"data": [
		{
			"id_category": 39231,
			"name": "laptops-und-zubehoer",
			"id_parent_category": 39161,
			"title_singular": "Laptop & Zubehör",
			"title_plural": "Laptops & Zubehör",
			"level": 4,
			"url": "https://www.kaufland.de/laptops-und-zubehoer/",
			"shipping_category": "D",
			"variable_fee": "5.90",
			"fixed_fee": 0,
			"vat": "19.00"
		},
		{
			"id_category": 46051,
			"name": "laptops",
			"id_parent_category": 39231,
			"title_singular": "Laptop",
			"title_plural": "Laptops",
			"level": 5,
			"url": "https://www.kaufland.de/laptops/",
			"shipping_category": "D",
			"variable_fee": "5.90",
			"fixed_fee": 0,
			"vat": "19.00"
		}
	],
	"pagination": {
		"offset": 0,
		"limit": 2,
		"total": 100
	}
}

Collection Pagination

Some API requests may return very large Collections of values. For example, you may have thousands of units for sale on the Kaufland marketplace, and a GET /units request would attempt to return all of them.

To make the responses more manageable, the results will be split into smaller groups or pages. Which page is returned in the response and how many Objects it contains are controlled by the limit and offset GET parameters. The default and maximum limit are endpoint dependent and are listed for each endpoint on the endpoint documentation page. The default offset is always 0.

Examples:

GET /categories will return 20 categories, since the default value of limit for the /categories endpoint is 20.
GET /categories?limit=15 will return 15 categories.
GET /categories?limit=10&offset=7 will return 10 categories, starting at the 8th one.

Each response which returns a Collection contains an additional object pagination in the body which provides information about offset, limit & total.

For example, in response to the request GET /categories/?limit=25&offset=5, the body will contain the following pagination information (assuming the total number of categories is 5530):

{
"data": [
	...
	],
	"pagination": {
		"offset": 5,
		"limit": 25,
		"total": 5530
	}
}

If you are familiar with SQL, the offset and limit query parameters behave just like the OFFSET and LIMIT SQL keywords.

Embedded Values

By default the API returns a default group of fields for each Object, but some endpoints allow optionally requesting additional fields. For example, when getting information about a single product (see code example below) it's possible to embed the product's category and units in the Product object. These optional fields are controlled through the embedded GET parameter, which contains a comma-separated list of desired additional fields.

For example, the request GET /product/20574181?embedded=category,units will return the product Object with the "category" property set to the product's category Object and the property "units" set to the the product's Collection of units.

Endpoints

All endpoints in the Marketplace Seller API require HTTPS encryption and start with https://sellerapi.kaufland.com/v2/. You can view documentation for the endpoints on the endpoints documentation page. This page also allows you to execute API requests directly from the documentation. Just fill in your Client Key and Secret Key in the fields at the top of the page and click Explore. Then you can expand any of the endpoint descriptions, fill in the fields, and click the "Try it out!" button. This will perform an API request to the server and display the results in the page.

Code Examples

For full code examples, see the Code Examples page.

Storefronts and Locales

Since Kaufland is expanding its Kaufland marketplace to other countries, many of the endpoints need either a storefront parameter or a locale parameter.

- storefront parameter (e.g. de) refers to a specific country (e.g. Germany) of the Kaufland marketplace. When doing a query e.g. for a certain product using /products/search endpoint you must specify in which countries marketplace you are searching. The reason is that the products might look different in every country, due to blacklisting, specific country legal regulations, different naming conventions and translations. All allowed storefronts can be found using this endpoint /info/storefront.
- locale parameter (e.g. de-DE) enables providing product data for different languages (e.g. German). All allowed locales can be found using this endpoint /info/locale.

IP Addresses

Marketplace Seller API by Kaufland is using the following IP addresses for Egress traffic (e.g. sending push notifications, downloading files):

35.234.86.109/32
34.107.121.244/32
34.141.72.142/32
34.159.54.64/32
34.141.104.142/32
35.234.120.175/32
34.89.165.188/32
34.159.150.215/32
34.159.155.87/32
34.159.78.247/32
34.89.252.217/32
35.198.94.0/32
35.246.147.218/32
34.89.153.171/32
34.107.96.82/32
34.89.168.105/32
34.159.137.130/32
35.198.148.202/32
34.159.211.19/32
34.159.98.126/32

Rest API

Overview

Requirements

Sending Requests

General Information

Required Headers

Signing Requests

Signature function

Full example Show

Signature function

Full example Show

Signature function

Full example Show

Reading Responses

Collection Pagination

Embedded Values

Endpoints

Code Examples

Storefronts and Locales

IP Addresses

Full example

Full example

Full example