Kaufland Adapter
NexusCommerce integration with the Kaufland Marketplace API for selling across European storefronts.
Overview
The Kaufland adapter connects NexusCommerce to the Kaufland Marketplace API, enabling sellers to manage product listings, sync orders, update inventory, and handle returns across Kaufland's European marketplace storefronts. Kaufland Global Marketplace operates storefronts in Germany (DE), Austria (AT), Czech Republic (CZ), Slovakia (SK), Poland (PL), and Romania (RO).
The adapter targets the Kaufland Marketplace API v2 and uses API key + HMAC-SHA256 request signing for authentication.
Key Concepts
Storefronts — Kaufland operates a separate marketplace per country. Each storefront has its own product catalog, orders, and inventory. Create one NexusCommerce connection per storefront you sell on.
EAN-based catalog — Like Bol.com, Kaufland uses EANs as the primary product identifier. Products are associated with Kaufland's central catalog by EAN. If your EAN is not in the Kaufland catalog, you must create a new catalog entry before listing.
Unit — Kaufland's term for a seller's offer on a product (equivalent to a listing). Units have a price, condition, available quantity, and shipping group. One EAN can have multiple units from different sellers.
HMAC Signing — Every Kaufland API request must include a signature computed from the request method, URI, body MD5, Content-Type, timestamp, and your secret key. NexusCommerce handles signing automatically.
Getting Started
Required Credentials
| Field | Description |
|---|---|
| Client Key | API client key from the Kaufland Seller Portal |
| Secret Key | API secret key from the Kaufland Seller Portal |
| Storefront | Two-letter storefront code (de, at, cz, sk, pl, ro) |
Obtain keys from the Kaufland Seller Portal: Settings > API Access > Generate API Keys.
Request Signing
NexusCommerce computes the HMAC-SHA256 signature as follows:
String-to-Sign = HTTP-Method + "\n"
+ URI + "\n"
+ MD5(RequestBody) + "\n"
+ Content-Type + "\n"
+ Timestamp
Signature = HMAC-SHA256(SecretKey, String-to-Sign)Required headers on every request:
HM-Client-Key: <client_key>
HM-Timestamp: <unix_timestamp>
HM-Signature: <computed_signature>
HM-Storefront: <storefront_code>
Accept: application/json
Content-Type: application/jsonThe timestamp must be within 900 seconds (15 minutes) of the server clock. Ensure NTP synchronization on the NexusCommerce server.
Storefront Codes
| Storefront | Code | Currency |
|---|---|---|
| Germany | de | EUR |
| Austria | at | EUR |
| Czech Republic | cz | CZK |
| Slovakia | sk | EUR |
| Poland | pl | PLN |
| Romania | ro | RON |
Synced Data
| Data Type | Direction | Kaufland API Endpoint | Notes |
|---|---|---|---|
| Products (Units) | Read / Write | /v2/units | Seller's listed units per EAN |
| Catalog Products | Read | /v2/products | Kaufland catalog product data |
| Inventory | Read / Write | /v2/units/{id} | Quantity per unit |
| Pricing | Read / Write | /v2/units/{id} | Price per unit (price and listing are the same resource) |
| Orders | Read | /v2/orders | All statuses with pagination |
| Order Items | Read | /v2/order-items | Line items with EAN and quantity |
| Shipment Confirmation | Write | /v2/order-items/{id}/ship | Per order-item shipment confirmation |
| Returns | Read | /v2/returns | Return requests |
Configuration Options
| Key | Type | Default | Description |
|---|---|---|---|
storefront | string | required | Two-letter storefront code |
sync_interval_minutes | integer | 60 | Polling frequency |
order_lookback_days | integer | 30 | Historical order window |
inventory_buffer_pct | integer | 0 | Safety stock reserve percentage |
default_condition | string | new | Default unit condition (new, used_very_good, used_good, used_acceptable) |
shipping_group | string | — | Default Kaufland shipping group ID |
price_sync_enabled | boolean | true | Push price updates to Kaufland |
warehouse_code | string | — | Warehouse identifier for multi-warehouse setups |
Supported Features
| Feature | Supported | Notes |
|---|---|---|
| Unit listing sync | Yes | Create and update seller units |
| Inventory updates | Yes | Per-unit quantity |
| Pricing updates | Yes | Price is part of the unit resource |
| Order sync | Yes | Polling only |
| Shipment confirmation | Yes | Per order-item confirmation |
| Returns management | Yes | View and acknowledge returns |
| Catalog product lookup | Yes | Read Kaufland catalog by EAN |
| New catalog entry creation | Yes | For EANs not in Kaufland catalog |
| Webhooks | No | Polling only |
| Multi-storefront | Yes | One connection per storefront |
| Advertising data | No | Not available via Marketplace API |
| FBK (Kaufland fulfillment) | No | FBK not supported in this adapter version |
Catalog Product Creation
If your EAN is not yet in the Kaufland catalog, you must create a catalog entry before listing units. NexusCommerce handles this automatically during the first sync:
- Adapter calls
GET /v2/products?ean={ean}to check if the EAN exists - If not found, adapter calls
POST /v2/productswith product data (title, description, brand, category, images) - Kaufland reviews the new catalog entry (typically 24–72 hours)
- Once approved, the adapter creates the unit listing
Track catalog entry status in the sync log. Entries in pending_review status will block unit creation until approved.
Rate Limits & Quotas
Kaufland enforces per-endpoint rate limits:
| Endpoint Group | Rate Limit |
|---|---|
| Units (read) | 25 req/s |
| Units (write) | 10 req/s |
| Orders | 25 req/s |
| Products (catalog) | 10 req/s |
| Returns | 10 req/s |
The adapter respects X-RateLimit-Remaining and X-RateLimit-Reset headers. When remaining quota drops below 20%, the adapter queues requests and resumes after the reset timestamp.
Kaufland also enforces a daily quota of 50,000 requests per API key. For large catalogs, contact Kaufland Seller Support to request a quota increase.
Troubleshooting
401 Unauthorized — Invalid signature
The HMAC signature is incorrect. Common causes:
- Clock skew between your server and Kaufland's API (>900 seconds). Verify NTP sync.
- The request body is not consistent between the MD5 calculation and the actual sent body.
- The secret key was regenerated in the Seller Portal but not updated in NexusCommerce. Update via Edit Credentials.
404 Not Found on unit creation
The EAN does not exist in the Kaufland catalog for the selected storefront. Each storefront has an independent catalog. Ensure the catalog product was created and approved on the correct storefront.
Orders stuck in need_to_be_sent status
Kaufland requires shipment confirmation for each order item individually. If using bulk order processing in NexusCommerce, verify that all line items in the order have been confirmed. A single unconfirmed item keeps the order in pending status.
Currency mismatch errors
Prices submitted to a storefront must use that storefront's native currency. NexusCommerce uses the currency defined in the storefront code table above. If your product catalog stores prices in EUR, enable the currency conversion setting in Settings > Marketplace > Kaufland > Auto-convert prices.
Catalog entry rejected by Kaufland
Kaufland rejects catalog entries that fail content quality checks. Common rejection reasons: missing brand attribute, images with watermarks or logos, titles containing promotional text (e.g., "SALE", "BEST PRICE"). Review the rejection reason in the sync log and correct the product data before re-submitting.
HM-Timestamp error after credential update
After updating credentials, the adapter generates a new timestamp for each request. If you receive timestamp errors immediately after setup, confirm that the system clock on the NexusCommerce API server is synchronized with an NTP source.