Kaufland Store Management
Connect your Kaufland Global Marketplace seller account to Odoo through the Kaufland Seller API v2. Every request is signed with HMAC-SHA256 using the Shop-Client-Key, Shop-Timestamp and Shop-Signature headers Kaufland requires, keyed with your own Client Key and Secret Key. Manage offers, orders, returns and inventory across all nine Kaufland storefronts from a single Odoo instance.
| Technical name | kaufland_store_management |
| Odoo versions | 17.0, 18.0, 19.0 (Community or Enterprise) |
| Current shipped version | 17.0 → 17.0.2.1.2, 18.0 → 18.0.2.1.2, 19.0 → 19.0.2.2.2 |
| Price | $499 USD — one-time, per Odoo version |
| Odoo module licence | OPL-1 |
The module installs and runs standalone — there is nothing to activate. Licensing is contractual (OPL-1).
The Seller API correction (the sellerapi.kaufland.com host and the Shop-* signature headers described on this page) ships in the 19.0 build. The 17.0 and 18.0 builds still call the old host with the old headers, so their syncs cannot authenticate with Kaufland. The correction for those series is tracked as its own release. Use the 19.0 build for a live Kaufland connection.
Key features
- Kaufland Seller API v2 with HMAC-SHA256 request signing over the raw body and exact URL
- All nine storefronts from one database: DE, CZ, SK, PL, AT, FR, IT, ES, NL
- Offers (units), products, product data by EAN and the shared catalogue
- Order and order-unit lifecycle — send, cancel, fulfil, refund — with shipping groups, carriers and labels
- Returns and return units — accept, reject, repair, clarify
- Inventory and live-status synchronisation, including bulk stock updates
- One contact per buyer: the order import and the customer sync share one partner resolver
- Push notifications for all 17 documented Kaufland events, with signature-verified delivery
- Seller support tickets and their messages
- Every published report, plus the bulk import-file interfaces, vouchers and variant suggestions
- Rate limiting against Kaufland's uniform 111 requests/second ceiling, with retry and backoff
- OWL dashboard with per-storefront KPIs and a Chart.js sales trend
- Onboarding wizard, connection tester, import/export wizards and a daily digest
- Order creation and the auto-workflow are opt-in switches, off after install or update
- Kaufland tab on products and sales orders: listing ids, 2-Person-Handling, localised titles, EPR numbers, Kaufland Pay reference and proof of delivery
Prerequisites
- Odoo 17, 18 or 19 (Community or Enterprise). Odoo Online (SaaS) cannot install third-party modules.
- A Kaufland Global Marketplace seller account with API access
- Your Client Key and Secret Key from the Kaufland Seller Portal
- The
requestsPython package
Installation
- Download the module ZIP for your Odoo version from your ECOSIRE Dashboard
- Extract it so
kaufland_store_management/sits inside a directory on youraddons_path:unzip ecosire-kaufland-*.zip -d /opt/odoo/addons/ - Restart the Odoo service:
sudo systemctl restart odoo
- Navigate to Apps, click Update Apps List
- Search for Kaufland Store Management and click Install
Configuration
Step 1: Get your Kaufland API credentials
- Sign in to your Kaufland Seller Portal
- Open your account's API access settings
- Copy your Client Key and Secret Key — one key pair covers every storefront
Step 2: Connect in Odoo
- Navigate to Kaufland → Configuration → Settings
- Create a configuration and enter:
- Client Key (
client_key) — your Kaufland API access key - Secret Key (
secret_key) — used for HMAC-SHA256 signature generation; stored as a password field - Storefront (
storefront) — Germany, Czech Republic, Slovakia, Poland, Austria, France, Italy, Spain or the Netherlands - Company (
company_id)
- Client Key (
- Click Test Connection to verify API access before importing anything
The Client Key and Secret Key fields are visible only to Settings administrators.
Step 3: Configure sync settings
Products and offers — the product and inventory syncs read and write your offers (units), which is the seller-side record Kaufland sells from. Product sync runs hourly, inventory every 15 minutes.
Orders — imported every 30 minutes once Create Orders from Kaufland is ticked (Step 4), with the order-unit lifecycle (send, cancel, fulfil, refund) pushed back to Kaufland. The payment-method mapping decides which Odoo journal a Kaufland payment lands in, and fulfilment pushes tracking numbers.
Customers — every 6 hours. The order import and the customer sync resolve a buyer through the same partner resolver, so the same buyer reaching Odoo through both paths is filed once.
Push notifications — subscribe to any of the 17 documented Kaufland events under Kaufland → Configuration → Push Subscriptions. Kaufland's subscription challenge handshake is answered automatically, and deliveries are accepted only when their signature verifies against an active subscription.
Step 4: Switch on order creation and the auto-workflow
Two switches on the Kaufland configuration, under Synchronization → Automation, decide whether the connector writes sales data into Odoo. Both are off after installing or updating the module, so an update never starts creating or confirming orders on its own.
| Switch | Technical name | What it does | Series |
|---|---|---|---|
| Create Orders from Kaufland | create_kaufland_orders | Creates sales orders, their lines and their customers from your Kaufland orders. While it is off, the scheduled order sync skips the configuration, push notifications and the Import Wizard create no orders, and Sync Orders tells you the switch is off. | 17.0, 18.0, 19.0 |
| Apply Auto-Workflow to Synced Orders | apply_auto_workflow | Runs your auto-confirm / auto-invoice / auto-deliver rules after each order sync. | 19.0 |
Tick Create Orders from Kaufland once Test Connection succeeds and your mappings are reviewed.
Before you tick Apply Auto-Workflow to Synced Orders, check the rules under Kaufland → Configuration → Auto-Workflow Rules or on the configuration's Auto-Workflow tab. The rules act on every open Kaufland order (draft or confirmed) of their own company, Kaufland configuration and storefront, not only the orders just imported. Orders from another Kaufland configuration, another storefront, or orders no configuration imported are never touched. A new rule defaults to the configuration's storefront. After an update, orders imported by an earlier build are linked to their configuration only where the company has exactly one Kaufland configuration. Where it has several, those older orders stay unlinked and no rule acts on them.
Kaufland tab on products and sales orders
Products and sales orders carry a Kaufland tab. On the product it shows the listing ids, the 2-Person-Handling flag, localised titles and the German packaging/EPR registration numbers. On the sales order it shows the marketplace order, storefront, 2-Person-Handling SLA, Kaufland Pay reference and proof-of-delivery link. On 19.0, Kaufland managers can add and delete rows on the configuration's Auto-Workflow and 2-Person-Handling tabs.
Initial sync
- Go to Kaufland → Operations → Import Wizard
- Select the data types to import (products, customers, orders)
- Set a date range for historical orders
- Start the import and monitor progress in Operations → Logs
Run a small import first and check the results before letting the scheduled actions take over.
API details
| Field | Value |
|---|---|
| Auth method | HMAC-SHA256 signature over method, exact URL and raw body — Shop-Client-Key, Shop-Timestamp, Shop-Signature headers |
| Base URL | https://sellerapi.kaufland.com/v2 |
| API version | v2 |
| Storefronts | de, cz, sk, pl, at, fr, it, es, nl |
| Rate limit | 111 requests per second per seller, uniform across endpoints |
| Retry policy | 3 retries, exponential backoff, on 429/500/502/503/504 |
| Key config fields | client_key, secret_key, storefront |
Endpoints your Odoo exposes
| Endpoint | Auth | Purpose |
|---|---|---|
/kaufland/webhook | public, signature-verified | Push notification receiver and subscription challenge handshake |
/kaufland/api/status | logged-in user | Connection and sync status |
/kaufland/api/sync | logged-in user | Triggers a sync from the dashboard |
/kaufland/dashboard/data | logged-in user | Dashboard KPI data |
Dashboard
The built-in OWL dashboard provides real-time visibility into your integration:
- 6 KPI cards — Revenue, Orders, Customers, Products, Average Order Value and Sync Health — each with period-over-period delta indicators
- Sales trend chart (Chart.js line chart) with interactive date filtering
- Order status breakdown showing the distribution across statuses
- Period filters — Today, 7 days, 30 days, 90 days, Year, or a custom range
- Activity feed of recent sync log entries
- Quick actions for Products, Orders, Customers, Queue, Logs and Settings
- Status footer with queue jobs, errors, out-of-stock items and sync rate
- Auto-refresh every 60 seconds, with dark mode support
Troubleshooting
| Issue | Solution |
|---|---|
| Connection failed | Re-check the Client Key and Secret Key and confirm they belong to the storefront you selected |
| Signature mismatch | The signature covers the exact URL and raw body — check that nothing rewrites the request in transit, and that the server clock is synchronised |
| Sync not running | Check that Odoo's scheduled actions are enabled and that the cron worker is running |
| Orders not importing | Check that Create Orders from Kaufland is ticked (it is off after install or update), then review the order status filters and the date range |
| Orders not confirmed or invoiced automatically | On 19.0, tick Apply Auto-Workflow to Synced Orders and check that the rule's company, configuration and storefront match the order |
| Records map to the wrong Odoo values | Correct the mapping records under the module's configuration, then re-run the import |
| Push events never arrive | Confirm the subscription is active and that the callback URL is reachable from the internet; a delivery whose signature does not verify is rejected with 403 and logged |
| Storefront not available | Valid storefronts are: de, cz, sk, pl, at, fr, it, es, nl |
| EAN required | Kaufland requires a valid EAN/GTIN for products |
| Module will not install | The extracted folder is not inside a directory on addons_path, or requests is missing from Odoo's Python environment |
Version history
| Odoo version | Version you download today |
|---|---|
| 17.0 | 17.0.2.1.2 |
| 18.0 | 18.0.2.1.2 |
| 19.0 | 19.0.2.2.2 |
This release makes order creation and the auto-workflow opt-in and adds the Kaufland tab to products and sales orders. Full detail: Kaufland Store Management.