This API version is deprecated. Please use the new Kaufland Marketplace Seller API version 2.

Inventory CSV Files

This page describes the file format of the inventory CSV files. For information on how to import these files into the Kaufland.de Onlineshop system, see the Managing Inventory page.

Overview

There are two types of inventory CSV files:

You can import both of these types of files by uploading the file to a publicly accessible web server and sending a POST request to the /import-files/ REST API endpoint. If the file is a Dump File, send the type as DUMP and if it is a Command File, send the type as COMMAND.

Dump Files

If you send an dump file to Kaufland.de Onlineshop, we will replace all of your current inventory data with exactly the data in the file. Anything that is not included in the file will be deleted from Kaufland.de Onlineshop, and all new and changed items will be updated. The below sections describe the Kaufland.de Onlineshop dump file format.

File Header

You should always include a header line in your Inventory CSV files. The header contains the names of the fields that will be set for the items in the file. The order of the fields in the file is not important. Here are the allowed fields for the file: 

ean;condition;price;comment;offer_id;warehouse;count;minimum_price;price_cs;minimum_price_cs;
     shipping_group;delivery_time_min;delivery_time_max

Descriptions for each field:

Field Required Max Length Description Example
ean Required 13 The EAN or ISBN. 5060004769643
condition Required 17 The condition of the item. A list of possible condition values is available under Conditions. New
price Required (if price_cs is not set) 10 The price of the unit in Eurocents. Maximum value of 1 million euros. 4999
comment Optional 128 A comment related to the item. The text is shown on the item page on the Kaufland.de Onlineshop site. Perfekter Zustand, wurde nie benutzt
offer_id Optional 40 An identifier from the seller which can be used for tracking. 439A-0218756
warehouse Optional 50 The warehouse the item is located in. Hauptlager
location Deprecated 5 The country the item is located in. ISO 3166 code values are allowed. The location field is only allowed if the warehouse field is not present. When the location field is specified, the system will select a random warehouse in the given country and assign it to the item. DE
count Optional 3 Number of unit(s) for sale in your inventory. If count > 1, the item will be offered for sale multiple times. 3
minimum_price Optional 10 The minimum price for the Tiefstpreis-Automatik (automatic lowest price adjustment) feature in Eurocents, when enabled for your account. 3999
price_cs Required (if price is not set) 10 The price of the item in Euros. Maximum value of 1 million euros. 49,99
minimum_price_cs Optional 10 The minimum price for the Tiefstpreis-Automatik (automatic lowest price adjustment) feature in Euros, when enabled for your account. 39,99
shipping_group Optional 255 Name of the shipping group for this item. A shipping group specifies countries the item can be delivered to at which price and by which carrier. paket
delivery_time_min Optional 6 The minimum amount of working days till the order arrives at the customer. If the delivery time is not available, use N/A. (Always use with delivery_time_max) 2
delivery_time_max Optional 6 The maximum amount of working days till the order arrives at the customer. If the delivery time is not available, use N/A. (Always use with delivery_time_min) 3

Example of a complete inventory export file: 

ean;condition;price;comment;offer_id;warehouse;count;minimum_price;price_cs;minimum_price_cs;
     shipping_group;delivery_time_min;delivery_time_max
5060004769643;100;1999;New games, perfect condition;AB12;Main Warehouse;3;;1499;;;packet;1;2
3546430118443;400;499;Pre-owned game, slightly scratched;AB13;Secondary Warehouse;1;;399;;;packet;2;3

Compatibility with import files added in Seller Portal and Seller API v2

The Kaufland Marketplace Seller API version 2 introduces capabilities not present in this API but which can affect the operation of this API. If you use only this API to make inventory modifications, these capabilities do not affect you. If you use this API in addition to the Seller Portal, or this API in addition to Seller API version 2, then your use of this API may be affected.

One new capability in Seller API v2 lets you list units for sale on additional storefronts of the Kaufland Marketplace (kaufland.cz and kaufland.sk in addition to kaufland.de). Along with that capability, there are tools to list a single distinct offer (as identified with id_offer) on multiple storefronts with differentiated attributes (e.g., pricing, shipping). When an offer is updated, some of its attributes are guaranteed to be synchronized across all storefronts (e.g., quantity, warehouse).

All Inventory CSV files added using this version of the API pertain to the German storefront. If you add inventory import files pertaining to other storefronts (using the Seller Portal or Seller API v2), those imports can cause changes to synchronized attributes in the German storefront (and vice-versa). To understand this more fully, please consult the documentation for Seller API version 2 inventory management and Seller API v2 Inventory CSV files.

Command Files

Command files are also a kind of CSV file, but without a header line at the top. Instead, the first field of each line contains a command and the subsequent fields vary based on the command. Because of the lack of a header, the subsequent fields must be in the expected order. The correct fields and order for each command is listed below. Kaufland.de Onlineshop accepts five different commands in command files. Every command consists of both required and optional fields.

Here are the available commands:

Command Description
UPSERT UPDATE or INSERT: either updates an existing offer or inserts a new one.
DELETE Stop offering an item for sale.
FLUSH Delete all offered items.
MARK_UNIT_SENT Mark an unit as sent.
MARK_UNIT_CANCELLED Mark an unit as cancelled.

UPSERT

The UPSERT command lists a new item for sale or, if a similar offer already exists, updates the existing offer. The following fields are allowed:

Field Required Description Example
ean Required The EAN or ISBN of the item. 5060004769643
condition Required The condition of the item. A list of possible condition values is available under Conditions. 100
price Required The price of the item in Eurocents. Maximum value of 1 million euros. 4999
comment Optional A comment related to the item. The text is shown on the item page on the Kaufland.de Onlineshop site. Perfekter Zustand, wurde nie benutzt
offer_id Optional An identifier from the seller which can be used for tracking. 439A-0218756
warehouse Optional Name of the warehouse the item is located in. For backwards compatibility reasons a country code is still accepted and mapped to any warehouse for this location. Hauptlager
count Optional Number of unit(s) for sale in your inventory. If count > 1, the item will be offered for sale multiple times. 3
minimum_price Optional The minimum price for the Tiefstpreis-Automatik (automatic lowest price adjustment) feature in Eurocents, when enabled for your account. 3999
price_cs Required (if price is not set) The price of the item in Euros. Maximum value of 1 million euros. 49,99
minimum_price_cs Optional The minimum price for the Tiefstpreis-Automatik (automatic lowest price adjustment) feature in Euros, when enabled for your account. 39,99
shipping_group Optional Name of the shipping group for this item. A shipping group specifies countries the item can be delivered to at which price and by which carrier. paket
(INTERNAL) Reserved This field is for internal use only and must be left empty.
(INTERNAL) Reserved This field is for internal use only and must be left empty.
delivery_time_min Optional The minimum amount of working days till the order arrives at the customer. If the delivery time is not available, use N/A. (Always use with delivery_time_max) 2
delivery_time_max Optional The maximum amount of working days till the order arrives at the customer. If the delivery time is not available, use N/A. (Always use with delivery_time_min) 3

The offer_id is saved with the unit and can be any string you use in your system to identify the offer. When the item is sold, the offer_id will be sent to you. To make the best use of this field, be sure to give every unit an offer_id. There is a restriction that for each item there can only be one unit with a given offer_id.

When deciding whether to do an update or an insert, the system looks at the ean, offer_id, and (if no offer_id is given), the condition. If an offer_id is given, then a new unit is created if you do not already have a unit with the same ean and offer_id. If no offer_id is provided, a new unit is created if you do not already have a unit with the same ean and condition.

DELETE

Issuing the DELETE command deletes your listing of an item from the Kaufland.de Onlineshop site. You must give the EAN of the item. If you specified one, you can also specify an offer_id, so that only the specified unit is deleted, not all units for the item.

Field Required Description Example
ean Required The EAN or ISBN of the item. 5060004769643
offer_id Optional The seller-defined unique ID of a unit that belongs to the item. 4390218756

FLUSH

The FLUSH command does not take any parameters. When Kaufland.de Onlineshop encounters a FLUSH command, it deletes all units from the seller who sent the file. This command is useful for deleting all items and re-listing them, when incremental updates are not possible.

MARK_UNIT_SENT

The MARK_UNIT_SENT command marks an item as shipped. This starts a background process which sends an email to the customer and (provisionally) transfers credit for the sale to the seller's account.

Field Required Description Example
ean Deprecated Please leave this field empty
offer_id Deprecated Please leave this field empty
id_order_unit Required The id_order_unit received in the order summary. 56896348978
carrier_code Required The shipping carrier that was used to send the item. The list of available codes is available in the Carrier Codes section of this page. If you cannot supply a tracking number for some reason, do not choose the kaufland.de Carrier Code, because then the tracking number field is mandatory. Instead, give the value Other or Other Hauler for the carrier. This changes the tracking_number field from required to optional.
For example, if you have shipped the package via DHL, but sent it book rate (Büchersendung), there is no tracking number for the package. So, you would specify Other for the carrier_code and leave the tracking_number field blank.		 DHL
tracking_number Required unless carrier_code is Other or Other Hauler Comma-separated list of tracking numbers of the package. AB34DE5,6ED43BA

MARK_UNIT_CANCELLED

The MARK_UNIT_CANCELLED command cancels the delivery of an item. This starts a background process which sends an email to the customer and transfers credit for the sale back to the customer's account.

Field Required Description Example
ean Required is at least one value. Leave other fields empty. The EAN or ISBN of the item. 5060004769643
offer_id The seller-defined unique ID of a unit that belongs to the item. 4390218756
id_order_unit The id_order_unit received in the order summary. 56896348978
reason Optional Reason for cancelling the order. The list of available reasons is available in the Cancellation Reasons section of this page. NoInventory

If you submit a value for more than one of the ID fields (EAN, offer_id, id_order_unit), then the system will search for units using an AND condition across all of the supplied fields. If you want to be sure you're only editing the exact unit you intend to, you should use only id_order_unit.

Examples

Here are some examples of lines from command files. 

UPSERT;5060004769643;New;4999;"Perfect condition, was never used";4390218756;;67;;;;;;2;3

With this command you are listing 67 units of the game "Sonic Rivals" for €49.99. The condition is set to new and there is an appropriate comment. The offer_id is 4390218756 and you state a delivery in two to three days. 

DELETE;5060004769643;4390218756

If you want to be sure you're editing exactly one unit, you should include an offer_id. This command deletes the listing you added above and specifies the offer_id 4390218756. Alternatively, you could have also run this command: 

DELETE;5060004769643

This would delete all of your units with this EAN.

If you want to change a listed item, you use the UPSERT command again: 

UPSERT;5060004769643;NEW;4499;"Perfect condition, was never used, now cheaper!";4390218756

This example updates the game in the above examples with a new price and comment. 

FLUSH;
UPSERT;5060004769643;NEW;4999;"Perfect condition, was never used";4390218756

This command deletes ALL of your units and then adds the same game again. 

MARK_UNIT_SENT;;;56896348978;DHL;012345678912

This command marks the unit with id_order_unit 56896348978 as shipped. Shipping carrier is DHL and the tracking number is 012345678912 

MARK_UNIT_CANCELLED;;;56896348978;NoInventory

This command cancels the unit with id_order_unit 56896348978 because the unit is not in inventory.

Conditions

Here are the allowed values for item condition. You can submit either the English or integer value.

String Integer
new 100
used - as new 200
used - very good 300
used - good 400
used - acceptable 500

Delivery Times (Deprecated)

When you submit a delivery time, you must use one of the following codes:

Code Description
a On Stock. Delivery in 1-2 working days.
b Delivery in 2-3 working days.
c Delivery in 4-6 working days.
d Delivery in 7-10 working days.
e Delivery in 11-14 working days.
f Delivery in 3-4 weeks.
g Delivery in 5-7 weeks.
h When it's available or no shipping estimate possible.
i Delivery in 8-10 weeks.

Carrier Codes

The following values are allowed for the carrier_code field:

Cancellation Reasons

Here are the allowed values for the reason field for cancellations, along with their meanings: