Kaufland Store Management
Connect your Kaufland Global Marketplace seller account to Odoo. The module speaks the Kaufland Seller API v2 directly, signing every request with your own Client Key and Secret Key, and covers all nine Kaufland storefronts from one Odoo database: Germany, Czech Republic, Slovakia, Poland, Austria, France, Italy, Spain and the Netherlands.
| 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 |
| Category | Connector |
This module installs and runs standalone. There is no licence client, no activation step and no key to enter — licensing is contractual (OPL-1). Install the ZIP and configure your Kaufland credentials.
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.
Requirements
| Requirement | Detail |
|---|---|
| Odoo | 17.0, 18.0 or 19.0, Community or Enterprise. Self-hosted or Odoo.sh — Odoo Online (SaaS) cannot install third-party modules |
| Odoo apps | base, sale_management, stock, account, delivery, mail, web, product, contacts — Odoo installs any that are missing |
| Python packages | requests |
| Platform account | A Kaufland Global Marketplace seller account with API access |
| Credentials | Your Client Key and Secret Key from the Kaufland Seller Portal |
Installation
- Download the ZIP for your Odoo version from your ECOSIRE Dashboard.
- Extract it into your addons path, so that
kaufland_store_management/__manifest__.pysits directly inside a directory listed inaddons_path. - Restart Odoo, then go to Apps → Update Apps List.
- Search for Kaufland Store Management and click Install.
There is no separate licence-client download and no activation step. If Odoo refuses to install, the cause is almost always the addons path in step 2 or a missing requests package.
Configuration
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.
Kaufland issues one key pair per seller account, not one per storefront — the storefront is selected in Odoo, not by a separate key.
2. Connect in Odoo
Go to Kaufland → Configuration → Settings and create a configuration:
| Field | Technical name | Type | Required |
|---|---|---|---|
| Configuration Name | name | Char | Yes |
| Client Key | client_key | Char | Yes |
| Secret Key | secret_key | Char | Yes |
| Storefront | storefront | Selection | Yes (defaults to Germany) |
| Company | company_id | Many2one | Yes |
| Timeout (seconds) | timeout | Integer | No (defaults to 30) |
Client Key and Secret Key are visible only to Settings administrators (base.group_system), and the Secret Key is stored as a password field.
Select the storefront this configuration sells on: Germany, Czech Republic, Slovakia, Poland, Austria, France, Italy, Spain or the Netherlands. One Odoo database can hold several configurations — one per storefront or per selling entity — and each keeps its own connection, sync state and dashboard.
Click Test Connection to verify the credentials against the live API before importing anything. The tester reports the platform's own error text when a call fails, and can save the values as a configuration on success.
3. How the module authenticates
Each request is signed with your Secret Key using HMAC-SHA256 over the exact request that is sent — method, URL including query string, and the raw body — and travels with the Shop-Client-Key, Shop-Timestamp and Shop-Signature headers Kaufland expects, plus Accept and User-Agent.
Two consequences worth knowing when you debug:
- The signature covers the body as sent. A proxy that rewrites the payload will invalidate it.
- The timestamp is part of the signature. A server clock that drifts far from real time will be rejected — keep NTP running.
Requests are rate-limited to Kaufland's documented uniform ceiling of 111 requests per second per seller, and a 429 is retried with exponential backoff.
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.
5. 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.
Scheduled actions
These are created on install and are how an unattended instance stays current:
| Scheduled action | Runs every | Enabled on install |
|---|---|---|
| kaufland: Sync Products | 1 hour | Yes |
| kaufland: Sync Orders | 30 minutes | Yes |
| kaufland: Sync Customers | 6 hours | Yes |
| kaufland: Sync Inventory | 15 minutes | Yes |
| kaufland: Test Connection | 1 day | Yes |
| kaufland: Cleanup Old Logs | 1 day | Yes |
The order sync runs on schedule but creates orders only while Create Orders from Kaufland is ticked on the configuration (see step 4).
Push notifications
Kaufland can push events to your Odoo instead of Odoo polling for them. Go to Kaufland → Configuration → Push Subscriptions and subscribe to any of the events Kaufland publishes:
order_new, order_unit_new, order_unit_status_changed, item_changed, category_changed, return_new, return_status_changed, return_unit_status_changed, item_unit_new, item_unit_changed, item_unit_deleted, item_unit_out_of_stock, item_unit_not_available, item_unit_available, item_unit_live, item_unit_not_live, buy_box_changed.
When you create or update a subscription, Kaufland immediately calls your callback with a challenge value and expects that value echoed back; the module answers the handshake for you, so a new subscription starts working without manual steps.
Deliveries arrive at /kaufland/webhook and are accepted only when the signature verifies against one of your active subscriptions, using your Secret Key. An unauthenticated caller gets HTTP 403, and a re-delivered event is de-duplicated on the platform's message id rather than processed twice. Kaufland requires an acknowledgement within 15 seconds; the module answers immediately and processes afterwards.
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, read by the dashboard |
/kaufland/api/sync | logged-in user | Triggers a sync from the dashboard |
/kaufland/dashboard/data | logged-in user | Dashboard KPI data |
Using the module
The menu is laid out as:
- Kaufland → Dashboard
- Kaufland → Orders
- Kaufland → Products
- Kaufland → Customers
- Kaufland → Operations — Import Wizard, Export Wizard, Mapping Wizard, Test Connection, Logs, Reports
- Kaufland → Configuration — Settings, Push Subscriptions
A normal first run is:
- Save the connection record and confirm Test Connection reports success.
- Review the mapping records so imported data lands on the right Odoo records.
- Tick Create Orders from Kaufland (and, on 19.0, Apply Auto-Workflow to Synced Orders once your rules are checked).
- Run a small import first — restrict it by date or to a handful of offers — and check the results before letting the scheduled actions take over.
- Watch the log records during the first full sync. Failures are recorded there rather than raised at the user.
What syncs
- Offers (units) — the seller-side record Kaufland sells from, including price, stock level, live status and per-storefront availability. Stock is updated through the unit's amount, and bulk stock through the bulk unit endpoint.
- Orders and order units — the full lifecycle: send, cancel, mark in fulfilment, refund, with shipping groups, carriers, labels and invoices.
- Returns and return units — accept, reject, repair or clarify a customer return.
- Customers — filed once per buyer. The order import and the customer sync both resolve a partner through the same resolver, so the same buyer arriving through two paths does not become two contacts.
- Products and the shared catalogue — products, product data by EAN, images, categories, attributes, tags, warehouses, vouchers and variant suggestions.
- Tickets, reports and subscriptions — seller support tickets and their messages, all published reports, and push subscriptions.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| The connection will not validate | Re-check the Client Key and Secret Key, and confirm the keys belong to the storefront you selected. A 401/403 on every call is a credential or signature problem, not a network one. |
Signature mismatch | The signature covers the exact URL and raw body. Check that nothing between Odoo and Kaufland rewrites the request, and that the server clock is synchronised. |
| Orders are not created / Sync Orders says the switch is off | Create Orders from Kaufland is off. It is off by default after installing or updating; tick it on the configuration under Synchronization → Automation. |
| Imported orders are not confirmed, invoiced or delivered automatically | On 19.0, tick Apply Auto-Workflow to Synced Orders and check that the rule's company, configuration and storefront match the order. |
| Nothing syncs even though the connection is fine | The scheduled actions are disabled at the Odoo level, or Odoo's cron worker is not running. Check Settings → Technical → Scheduled Actions and that --max-cron-threads is greater than zero. |
| Sync starts then stops part-way | Read the module's log records for that run. Rate limiting and rejected field values are the two common causes; both are logged with the platform's own error text. |
| Push events never arrive | Confirm a subscription is active, that the callback URL is reachable from the public internet, and that it answers the challenge handshake. A webhook whose signature does not verify is rejected with 403, and the rejection is logged. |
| Duplicated products or customers | Run the initial import once. If a first attempt half-finished, review the existing records before re-running rather than importing on top. |
| Records import but map to the wrong Odoo values | Fix the mapping records under the module's configuration, then re-run the import. |
The requests library is required | requests is missing from the Python environment that runs Odoo. Install it into that interpreter. |
| Odoo refuses to install the module | The extracted folder is not inside a directory listed in addons_path. See Installation. |
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 |
ECOSIRE module versions are <odoo major>.<module major>.<minor>.<patch>, so 19.0.2.2.2 is the Odoo 19 build of module version 2.2.2. Your installed version is shown in Apps.
What changed in this release
19.0.2.2.2, 18.0.2.1.2, 17.0.2.1.2
- Order creation is opt-in. Orders and their customers are created only while the new Create Orders from Kaufland switch is ticked. It is off after installing or updating, so an update never starts creating orders from old settings.
- The auto-workflow is opt-in (19.0). The auto-confirm / auto-invoice / auto-deliver rules run only while Apply Auto-Workflow to Synced Orders is ticked. Each rule acts only on open orders of its own company, Kaufland configuration and storefront.
- Kaufland tab on products and sales orders. The listing ids, 2-Person-Handling flag, localised titles and packaging/EPR numbers on the product, and the marketplace order, storefront, 2PH SLA, Kaufland Pay reference and proof-of-delivery link on the order, are visible again on 19.0 and newly shown on 17.0 and 18.0.
- Kaufland managers can delete rows on the Auto-Workflow and 2-Person-Handling tabs (19.0). Before, saving after a deletion failed with an access error.
19.0.2.2.1 and earlier
- The connector talks to
sellerapi.kaufland.comand signs requests with theShop-Client-Key/Shop-Timestamp/Shop-Signatureheaders Kaufland actually requires. Earlier builds called a host that does not exist and could not authenticate at all. - Order fulfilment uses
/order-units(send,cancel,fulfil,refund); returns usePUT /returns/{id}and customer returns/return-units(accept,reject,repair,clarify). - Push notifications are real: all 17 documented events can be subscribed to from Odoo, with verified delivery and a working subscription challenge handshake.
- All nine storefronts are selectable, and the dashboard and "sync now" act on the same store.
- Client Key and Secret Key are restricted to Settings administrators.