Skip to main content

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 namekaufland_store_management
Odoo versions17.0, 18.0, 19.0 (Community or Enterprise)
Current shipped version17.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 licenceOPL-1
No licence key and no activation step

The module installs and runs standalone — there is nothing to activate. Licensing is contractual (OPL-1).

Odoo 17.0 and 18.0: order sync cannot reach Kaufland yet

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 requests Python package

Installation​

  1. Download the module ZIP for your Odoo version from your ECOSIRE Dashboard
  2. Extract it so kaufland_store_management/ sits inside a directory on your addons_path:
    unzip ecosire-kaufland-*.zip -d /opt/odoo/addons/
  3. Restart the Odoo service:
    sudo systemctl restart odoo
  4. Navigate to Apps, click Update Apps List
  5. Search for Kaufland Store Management and click Install

Configuration​

Step 1: Get your Kaufland API credentials​

  1. Sign in to your Kaufland Seller Portal
  2. Open your account's API access settings
  3. Copy your Client Key and Secret Key — one key pair covers every storefront

Step 2: Connect in Odoo​

  1. Navigate to Kaufland → Configuration → Settings
  2. 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)
  3. 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.

SwitchTechnical nameWhat it doesSeries
Create Orders from Kauflandcreate_kaufland_ordersCreates 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 Ordersapply_auto_workflowRuns 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​

  1. Go to Kaufland → Operations → Import Wizard
  2. Select the data types to import (products, customers, orders)
  3. Set a date range for historical orders
  4. 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​

FieldValue
Auth methodHMAC-SHA256 signature over method, exact URL and raw body — Shop-Client-Key, Shop-Timestamp, Shop-Signature headers
Base URLhttps://sellerapi.kaufland.com/v2
API versionv2
Storefrontsde, cz, sk, pl, at, fr, it, es, nl
Rate limit111 requests per second per seller, uniform across endpoints
Retry policy3 retries, exponential backoff, on 429/500/502/503/504
Key config fieldsclient_key, secret_key, storefront

Endpoints your Odoo exposes​

EndpointAuthPurpose
/kaufland/webhookpublic, signature-verifiedPush notification receiver and subscription challenge handshake
/kaufland/api/statuslogged-in userConnection and sync status
/kaufland/api/synclogged-in userTriggers a sync from the dashboard
/kaufland/dashboard/datalogged-in userDashboard 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​

IssueSolution
Connection failedRe-check the Client Key and Secret Key and confirm they belong to the storefront you selected
Signature mismatchThe 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 runningCheck that Odoo's scheduled actions are enabled and that the cron worker is running
Orders not importingCheck 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 automaticallyOn 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 valuesCorrect the mapping records under the module's configuration, then re-run the import
Push events never arriveConfirm 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 availableValid storefronts are: de, cz, sk, pl, at, fr, it, es, nl
EAN requiredKaufland requires a valid EAN/GTIN for products
Module will not installThe extracted folder is not inside a directory on addons_path, or requests is missing from Odoo's Python environment

Version history​

Odoo versionVersion you download today
17.017.0.2.1.2
18.018.0.2.1.2
19.019.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.

Support​