Managing Inventory
Basic Inventory Concepts
You as a seller may sell the same product in many different ways.
Two copies of a book for sale may both be in used condition, but show very different signs of use.
Or you sell many copies of one book in new condition, with some stored in one warehouse and some in another warehouse (such that handling and transport times differ).
The Kaufland marketplace permits you to save an id_offer
on inventory units to uniquely identify different units of the same product, so these similar units can be tracked and managed independently of one another.
Every inventory change is performed with respect to a single storefront.
Inventory changes performed directly by REST API specify the storefront, and adding an inventory CSV file requires specifying which storefront the file pertains to.
If you are selling on multiple storefronts, units will be connected via your id_offer
.
When units are connected by id_offer
, we ensure that their warehouse and quantity are kept in sync.
Other properties of connected units are allowed to differ by storefront and are not kept in sync (e.g., prices, shipping group, handling time, note).
If you don't want inventory and warehouse to be considered as shared information between two units, they must have different id_offer
.
In order to minimize erroneous synchronization of quantity and warehouse, we will reject attempts to create a unit if we already store a unit with same id_offer
and different EAN or condition, or which is fulfilled by Kaufland.
id_offer
field must be UNIQUE across the seller's entire inventory.
For example, if you use the
id_offer
value "xyz-123"
to offer a product,
then you cannot use the same id_offer
value "xyz-123"
for any other offer
unless offering same Product in a different storefront.
Creating Units
Once you have added an product to the Kaufland marketplace (see the Managing Product Data page), or if the product already exists on the site, you need to add your inventory information. There are two ways to do this:
- REST API: use the
/units/
endpoint to upload inventory data one product at a time. - CSV Files: use the
/import-files/
REST API endpoints to send inventory data for multiple products at once.
Adding new inventory with the REST API
The simplest way to update your inventory data is to send JSON requests to the /units/
REST API
endpoint. However, you can only update one product at a time this way, so far large volumes of changes,
sending CSV files is more efficient.
Note: We prevent this action for units fulfilled by Kaufland and respond with an HTTP 403 error code. Read more about FBK.
To use this endpoint, you need to send a POST
request with a JSON object that describes your
inventory. Here's an example JSON object:
{
"id_product": 35903281,
"ean": "4011905437873",
"condition": "NEW",
"listing_price": 5999,
"minimum_price": 5100,
"amount": 200,
"note": "",
"id_offer": "AB1234",
"handling_time": 2,
"id_warehouse": "1345",
"id_shipping_group": "3457",
"storefront": "de"
}
Here are explanations for each property of the object:
-
id_product
: The internal Kaufland ID of the product. You must either specify anid_product
orean
(or both). -
ean
: The EAN of the product. You must either specify anid_product
orean
(or both). -
condition
: "NEW" means that the product is not used. The available conditions are listed below. -
listing_price
: The price you would like to sell the product at, in integral cents in the currency of the storefront (CZK or EUR). This value must be greater than zero, and has a maximum that differs by currency (maximum 25 million CZK or 1 million EUR). -
minimum_price
: The minimum price you would be willing to sell at, in integral cents of the storefront currency. If this property is specified, and you have enabled automatic price adjustment (i.e. Tiefstpreis-Automatik) on your account, the price of your inventory will automatically be adjusted in order to increase your buybox position, but not below this price. -
amount
: How many of the product you have in stock. Note that amount is limited to 99999. -
note
: A note about the products condition for the customer. This gives some extra details for used products. This is limited to 250 characters. -
id_warehouse
: The warehouse ID the product is located in. If not specified, your default warehouse. -
id_offer
: Your internal ID for the unit (offer and unit are synonyms on the Kaufland marketplace). Whatever you set here will be included in the unit, but not the product data. This is used to identify units which should be connected over several storefronts. Read more here. -
handling_time
: The amount of working days till the order is handed over to the carrier. (Always use withtransport_time
, which is part of the shipping group.) Has to be equal to or bigger than zero [>=0]. -
id_shipping_group
: ID of the shipping group the unit should be assigned to. -
storefront
: The storefront parameter indicates on which marketplace the offer should be placed.
If you get a 201
response code, then the unit was created successfully. Otherwise,
you should get a JSON object back with an error message in the message
property, for example:
{
"message": "Can not decode body"
}
Note: The POST /units/
endpoint should be used to add new units to an product. However, if you send
data for an product for which you already have a unit, it might update the existing unit, instead of creating a
new unit. Here are the rules for what happens:
When a new unit is created:
- You have no existing units for the product on the same storefront.
- You have existing units for the product on the same storefront, and they do not have an
id_offer
set, and the newly submitted unit has noid_offer
, but the new unit has a differentcondition
than all of the existing units. - You have existing units for the product on the same storefront, and they do not have an
id_offer
set, but the new unit has anid_offer
. - You have existing units for the product on the same storefront, and they have an
id_offer
set, but the new unit has a differentid_offer
. - You have existing units for the product on the same storefront, and they have an
id_offer
, but you send a new unit without anid_offer
.
When an existing unit is updated:
- You have existing units for the product on the same storefront, and they do not have an
id_offer
set, and the newly submitted unit has noid_offer
, but the new unit has the samecondition
as one of the existing units. - You have existing units for the product on the same storefront, and they have an
id_offer
set, and the new unit has the sameid_offer
as one of the existing units.
Available Conditions
String | Integer |
---|---|
"NEW" | 100 |
"USED___AS_NEW" | 200 |
"USED___VERY_GOOD" | 300 |
"USED___GOOD" | 400 |
"USED___ACCEPTABLE" | 500 |
Updating inventory with CSV files
Since you can only add or update one product at a time through the /units/
REST API endpoint,
it can be more efficient to send a batch file with many units in it. There are two types of inventory CSV files:
- INVENTORY FEED file: a full dump of your entire inventory. Details about this type of file are available on the Inventory CSV Files page.
- INVENTORY COMMAND file: a list of commands to alter your existing inventory in the Kaufland marketplace. Details about this type of file are available on the Inventory CSV Files page.
Retrieving Units
You can get a list of all of your own units by sending a GET
request to the
/units/
endpoint. Note: it can take
several minutes for units to show up in this list after they are created.
Note: By default this endpoint only returns units which need to be fulfilled by the seller. To get units fulfilled by Kaufland an appropriate filter parameter needs to be applied. Read more about FBK.
Updating Units
To update a single unit, send a PATCH
request to the /units/{id_unit}/
REST API endpoint, replacing {id_unit}
in the URL with the internal Kaufland ID of the unit. The
body of the request should contain a JSON object, similar to the JSON you send to create a new unit,
with one difference: you cannot change the id_product
or id_offer
of a unit. To change
those properties, you must delete the unit and create a new one.
Note: We prevent this action for units fulfilled by Kaufland and respond with an HTTP 403 error code. Read more about FBK.
Note: you can also update units by sending a POST
request to the
/units/
endpoint. See the above
note on updating with a POST request for details.
Deleting Units
To delete a unit, send a DELETE
request to the /units/{id_unit}/
endpoint, replacing {id_unit}
in the URL with the internal Kaufland ID of the unit.
Note: We prevent this action for units fulfilled by Kaufland and respond with an HTTP 403 error code. Read more about FBK.
Retrieving Single Units
You can get the stored information for a single unit if you have its ID. Just send a GET
request to
the /units/{id_unit}/
endpoint, replacing
{id_unit}
in the URL with the internal Kaufland ID of the unit.