Kaufland Marketplace Connector for OpenCart

Overview

Sells your OpenCart catalogue on the Kaufland Global Marketplace (Germany, Czechia, Slovakia, Poland, Austria and the other storefronts of the Kaufland Seller API): category and attribute mapping, price rules, product data and unit creation by EAN, stock and price bulk updates, order import into real OpenCart orders, carrier code and tracking per order unit, returns and cancellations.

What it does

• Maps OpenCart categories to Kaufland categories and product attributes to Kaufland attributes (shared-set values are matched by label), with a price markup per category or product, price endings and a stock buffer.
• Lists mapped products by EAN: when the EAN already exists in the Kaufland catalogue the unit (your offer with price, stock and handling time) is created at once; otherwise your product data is sent first and the unit follows when Kaufland reports the product ready. The reason is shown per product when Kaufland refuses it.
• Pushes stock and price as bulk unit updates (up to 150 units per call) on a schedule and when a product changes, and reads the result per unit.
• Imports Kaufland orders into OpenCart without duplicates (buyer, delivery and billing address, company name, prices as sold, shipping). An order waits until Kaufland has added the addresses (status need_to_be_sent). Units of the same product become one order line.
• Marks every order unit as sent with the Kaufland carrier code and the tracking number from the order history, follows status changes (sent, received, returned, cancelled), and cancels units you cannot supply with one of the Kaufland cancel reasons.
• Imports return units and accepts them from the admin.
• Optional push notifications (subscriptions): Kaufland tells the shop that something changed, the importer runs at once; the scheduled job remains the safety net.
• Optional EU product safety contact (GPSR) sent with every product you list.
• You create your own API key pair (Client Key and Secret Key) in the Kaufland Seller Portal; the Secret Key is stored encrypted. Test mode uses the Kaufland Seller API Playground.
• A job queue with automatic retries (5 minutes, 15 minutes, 1 hour, 3 hours, 12 hours), a log with filters and CSV export.

Trademark

Kaufland is a trademark of its owner. This extension is an independent product of Kavio Labs, not affiliated with, endorsed or sponsored by Kaufland. It uses the public Kaufland Marketplace Seller API under your own seller account and API keys and is subject to Kaufland's seller terms.

Compatibility

• OpenCart 4.1 (tested on 4.1.0.4); PHP 7.4 or newer with the cURL and OpenSSL extensions.
• No OCMOD, no core edits. The queue runs from the OpenCart cron (see Configuration).

Next steps

Installation and setup

Requirements

• OpenCart 4.1 (tested on 4.1.0.4), PHP 7.4 or newer with the cURL and OpenSSL extensions.
• Administrator access to the admin.
• A Kaufland seller account with API access. In the Kaufland Seller Portal (API settings) create a key pair: a Client Key (32 characters) and a Secret Key. The same pair works for the live API and for the Playground.
• For test mode: the Kaufland Seller API Playground must be activated for your account by Kaufland (Kaufland states this can take up to two weeks). The Playground is an isolated environment with test data; it offers units, orders, shipments, returns and subscriptions, but no product data, categories, attributes or carriers.
• In the Seller Portal: at least one shipping group (its ID is optional on the Connection page; without it Kaufland uses your default shipping group) and your storefront(s) activated.
• Products with a valid EAN as the barcode and images that are reachable from the internet (Kaufland downloads them).
• A public https address for your store if you want push notifications.
• The OpenCart cron line on your server (see step 5 of the installation).

Install the extension

1. In the admin go to Extensions > Installer, upload kv_kaufland.ocmod.zip and click Install.
2. Extensions > Extensions, choose "Modules", find "Kaufland Marketplace Connector" and click Install (the green button).
3. Click Edit. Switch the connector on and, if you have one, enter your Kavio Labs license key. Without a key the extension works for 14 days.
4. The Kaufland pages are under Sales > Kaufland: Listings, Connection, Categories, Attributes, Rules, Orders, Returns, Log, Jobs.
5. Cron. The install registers an hourly entry in the OpenCart cron, which needs the standard OpenCart cron line on your server (shown on the settings page). For a faster sync call the secret web address from the settings page every few minutes with your host cron.

Connect Kaufland

1. Open Sales > Kaufland > Connection.
2. Enter the Client Key and Secret Key for the mode you want (the same pair may be used in both), choose your storefront (Kaufland.de, .cz, .sk, .pl, .at and the others the Seller API lists), and optionally the shipping group ID, warehouse ID, a notification e-mail and the product safety contact. Press Save and test: a green message names the storefront and the number of shipping groups found.
3. Start in Test mode (Playground): unit, order, shipment and return calls go to the isolated test environment; categories, attributes and carriers are read from the live API (read only) because the Playground does not have them; product data is never sent in test mode.
4. Switch to Live mode after a successful test and test again. Products and prices now go to your real Kaufland shop.
5. Set up categories, attributes and rules (see Usage).
6. Optional push notifications (Live mode): save a notification e-mail address, then press Register webhook at Kaufland. Kaufland calls your shop once to verify the address and then sends a signed notification when an order unit or a return unit changes status. Your shop must be reachable from the internet over https.

Update

Upload the new package in Extensions > Installer. Settings, credentials and data are kept; missing tables and settings are added on the first request after the update.

See CHANGELOG for what changed in each version.

Uninstall

Extensions > Extensions > Modules > Kaufland Marketplace Connector > Uninstall removes the mappings, rules, queue, log and the stored credentials. The OpenCart orders that were imported stay. Units already on Kaufland stay there; remove them in the Seller Portal if you do not want them offered.

Configuration

Settings page

Extensions > Extensions > Modules > Kaufland Marketplace Connector > Edit. The page also holds the licence card.

Connection (Sales > Kaufland > Connection)

Credentials are stored encrypted (AES-256-GCM, key derived from your store's own encryption key), never shown again, and an empty secret field keeps the saved value.

Rules (Sales > Kaufland > Rules)

Markup in percent and a fixed amount, price endings, list price, exchange rate (1 = use the OpenCart currency of the storefront currency code), stock buffer, zero limit, maximum, handling time in days (0 to 100, default 2), VAT default, default brand and brand source (manufacturer or a product attribute), default weight, automatic unit creation, the own-carrier tracking switch, tracking link template and the status mapping from Kaufland to OpenCart order statuses. Reporting tracking to Kaufland is on by default because Kaufland needs it to mark an order unit as sent. Markup can also be set per category (Categories page) and per product.

Cron

The install registers an hourly entry in the OpenCart cron (Extensions > Cron Jobs). For a faster sync call the secret web address shown on the settings page every few minutes:

https://your-shop.example/index.php?route=extension/kv_kaufland/channel/kaufland.cron&key=<secret>

Overlapping runs are prevented. A wrong key answers 403.

Push notifications (optional)

The callback address is https://your-shop.example/index.php?route=extension/kv_kaufland/channel/kaufland.webhook&c=0. It answers the subscription check of Kaufland (mode=subscribe&challenge=...) and accepts signed notifications; an unsigned or wrongly signed call is rejected. Events are stored as jobs (one per Kaufland message id) and the queue does the work.

Log and jobs

• Log lists every call, job and notification with filters and a CSV export.
• Jobs lists the queue. A failed job is retried after 5 minutes, 15 minutes, 1 hour, 3 hours and 12 hours, then marked "Gave up"; use Retry to queue it again, or "Run the queue now".

Usage

First listing

1. Categories: search the Kaufland category tree (leaf categories only) and map an OpenCart category to one, with an optional markup and a manufacturer (brand) name. The tree is loaded with one call per storefront and cached for a day; press Refresh reference data after Kaufland changes categories.
2. Attributes: for the chosen Kaufland category the required attributes are listed first, then the optional and conditional ones. Map each to a product attribute, the manufacturer, the model or a fixed value. Values of attributes that have a shared set (for example a colour list) are matched by their label and sent as the Kaufland value; other values are sent as typed. Title, description, pictures, category, manufacturer and EAN come from the OpenCart product and are not offered for mapping.
3. Rules: markup, price endings, stock buffer, handling time (days), default brand, weight, and whether the extension creates units automatically.
4. Listings: map products (one by one or a whole OpenCart category). The product id and the EAN go in the form; the EAN is the offer SKU. Mapped products without a unit are created on the next sync.
5. Watch the Listings page: a product shows Waiting while Kaufland processes it, Live when its unit exists, or the exact reason Kaufland gave (for example the attributes it misses). Fix the data and press Retry.

What happens when you list a product

• The EAN already has a Kaufland product page (someone else listed it): the extension creates your unit (price, stock, handling time, condition NEW, shipping group) at once. Kaufland matches your offer to the existing product; your own title and images are not used for it.
• The EAN is new to Kaufland: the extension sends your product data (title, description as plain text, pictures, category, manufacturer, mapped attributes, product safety contact) and then polls the product data status. Kaufland processes it asynchronously and may review it manually, which can take hours or days. When the product is ready the unit is created. Until then the batch shows Waiting; after four hours the listing shows a retry message, and Retry continues (the product data is not sent again when the product is ready by then).
• Product data cannot be sent in test mode; use Live for new products.

Stock and price

Stock and price are pushed as bulk unit updates (one call per 150 units) on the schedule and whenever a mapped product is saved. Sync now queues an immediate push and order import. Prices are integer cents of the storefront currency (EUR, CZK or PLN); the OpenCart price is converted with the OpenCart currency of the same code or the fixed rate on the Rules page.

Orders

• Kaufland creates an order unit with status open when a customer buys; about 15 minutes later it becomes need_to_be_sent and carries the addresses. The extension imports an order once all its units are past open: buyer, delivery and billing address (street and house number joined), company name, and the prices as sold. Units of the same product become one line with the quantity.
• A line whose EAN is not mapped is not imported: the Orders page shows the reason and the import is retried every hour.
• Status changes at Kaufland (sent, received, returned, cancelled) follow into OpenCart through the status mapping.
• When you set an imported order to the Shipped status and write the tracking number in the order history (for example Tracking: 00340434161094042557 carrier: DHL), the extension marks every order unit of the order as sent. The carrier name is matched to the Kaufland carrier list (for example DHL, Deutsche Post, DPD); a carrier that is not in the list is sent as Other.
• Cannot supply on the Orders page cancels the order units at Kaufland with the reason you choose from the Kaufland list (default NoInventory).
• The OpenCart order has the lines at the price Kaufland sold and a shipping row with the shipping rates of the order units, in the currency of the storefront (EUR, CZK or PLN). The order history notes the Kaufland order number and its total.

Returns

Return units appear on the Returns page linked to the OpenCart order. Approve accepts the return units that arrived at your warehouse. Clarify, reject and repair are done in the Kaufland Seller Portal. Refunds are issued by Kaufland.

Jobs, log and connection

• Jobs: counts per state, the list with the last error, Retry, Remove and Run the queue now.
• Log: filter and export what happened and when.
• Connection: keys, storefront, shipping group, notification e-mail, product safety contact, Test connection, push notification registration.

Limits worth knowing

• Kaufland allows 111 requests per second per seller across all endpoints; the queue retries after a 429 answer.
• Bulk unit updates take at most 150 units and no duplicates per call.
• A new unit appears in the unit list of the API only after up to several minutes; the extension remembers the unit ids it created.
• The Kaufland Seller API has no unit price or stock history; the extension shows the last values it pushed.
• Invoices are not uploaded in version 1.0 (the API has an order invoice upload; it is on the roadmap).

Developer notes

Technical notes for developers who customize Kaufland Marketplace Connector for OpenCart. The API client (src/Client/Api.php), the mapper and the driver are shared in design with the CS-Cart add-on of the same name; tests/unit.php checks every request the client sends against tests/samples/official-operations.json.

Kaufland is a trademark of its owner. This extension is an independent product by Kavio Labs, not affiliated with, endorsed or sponsored by Kaufland.

Identity

Structure

Controllers: admin/controller/channel/kaufland.php (pages and actions), catalog/controller/channel/kaufland.php (cron, webhook, invoice link, stock event). No OCMOD, no core edits.

API conformance (official Kaufland documentation)

Verified 2026-11-06 against the OpenAPI specification published by Kaufland (https://sellerapi.kaufland.com/swagger.json, version 2.47.0; tests/samples/official-operations.json holds the method and path of every operation). Unit-tested: every request the client sends in tests/unit.php must match an operation in that file. The mock server in tests/mock-server/server.js follows the same specification, verifies the request signature like Kaufland does and enforces the order unit rules (integer cents, need_to_be_sent before sending, 207 for bulk updates, the subscription challenge).

All requests carry Shop-Client-Key, Shop-Timestamp and Shop-Signature, a User-Agent and Accept: application/json (documentation: https://sellerapi.kaufland.com/rest-api). Kaufland offers no sandbox for the catalogue endpoints, so the unit tests and the mock are built from the specification; the Playground serves units, orders, shipments, returns and subscriptions.

Test without Kaufland

Set the setting module_kv_kaufland_base_url (development only) to the address of the mock including /v2, for example http://127.0.0.1:11960/v2.

• node tests/mock-server/server.js 11960 starts the stand-in.
• php tests/unit.php runs the unit tests (PHP 8.1 and 8.3).
• node tests/e2e.js runs the browser test against a dev store with the extension installed.

Troubleshooting

"Test connection" fails

• Check the mode and the storefront. Test mode needs the Playground to be activated for your account (Kaufland says this can take up to two weeks); until then use a read-only live check by switching to Live.
• Check for spaces before or after the Client Key and Secret Key. "The signature does not match" (corrupted-signature) means a wrong Secret Key; "Invalid client key" (invalid-credentials) a wrong Client Key; a missing-or-invalid-request-header answer can mean that the server clock is more than five minutes off (the request timestamp is checked).
• storefront-not-configured: the chosen storefront is not activated for your seller account.
• The Log tab shows Kaufland's answer (masked): the problem type, the message and the field errors.
• Your server must be able to reach the provider over HTTPS (outgoing port 443) and have a current CA bundle.

Nothing happens after an order changes status

• Check that the connector is enabled on its settings page (Extensions > Extensions > Modules).
• Check the license status bar on the extension pages.
• Open Jobs: queued jobs wait for cron. If the counts never change, the cron job is not running; open the secret web address from the settings page once, or use Run the queue now on the Jobs page.

A job is "Waiting to retry" or "Gave up"

The last error is shown in the list. Fix the cause (credentials, data, provider outage) and press Retry. Jobs are retried automatically after 5 minutes, 15 minutes, 1 hour, 3 hours and 12 hours before they give up.

Webhooks are rejected

• Kaufland signs notifications with your Secret Key; the key of the mode you registered in must be the one saved on the Connection page. The Playground signs with a separate test key that Kaufland's partner management hands out on request, so notifications from the Playground may be rejected.
• The web address must be the one on the Connection page, reachable from the internet over https and not behind a login or an IP filter. Registration fails when Kaufland cannot fetch the address (it must answer the challenge within 15 seconds).
• Rejected notifications are only a delay: orders are also read by the scheduled job.
• Rejected events are listed in the log with the action "webhook".

A product stays "Waiting" or shows a Kaufland message

• New EANs: Kaufland processes product data asynchronously and may review it by hand (hours to days). After four hours the listing shows a retry message; press Retry later.
• "missing attributes": map the listed Kaufland attributes on the Attributes page.
• "blocked on Kaufland": the product is blocked by Kaufland (see the reason code in the message); contact Kaufland.
• A unit is not created for an EAN whose product data was rejected until the data is fixed.

An order is not imported

Orders wait until Kaufland moved every unit from open to need_to_be_sent (about 15 minutes after the purchase). Unmapped EANs are shown on the Orders page and retried every hour.

The cron address answers "Forbidden"

The key in the address is wrong. Copy the address again from the settings page.

Still stuck

Write to us from your purchase page with the extension version, the OpenCart version and the relevant log lines (secrets are masked automatically).

FAQ

Which OpenCart versions are supported?

OpenCart 4.1 (tested on 4.1.0.4) with PHP 7.4 or newer. This package is for OpenCart 4 only.

Does it change the OpenCart core?

No. It uses events and its own admin pages; no OCMOD, no core edits.

Where are my credentials stored?

In your own database, encrypted. The key is derived from your store's own encryption key, so a database dump alone does not reveal them. They are never shown again after saving.

Do I need my own Kaufland API keys?

Yes. You create a Client Key and a Secret Key in the Kaufland Seller Portal (API settings) and enter them on the Connection page. The extension never uses a shared key.

Is there a test environment?

Kaufland offers the Seller API Playground: isolated test data with the same keys, activated on request (Kaufland says up to two weeks). It has units, orders, shipments, returns and subscriptions but no product data, categories, attributes or carriers, so test mode reads those from the live API (read only) and never sends product data.

Why is an EAN required?

Kaufland builds offers on products identified by EAN. The barcode of the mapped product is the EAN of the product data and of the unit.

Which Kaufland countries are supported?

The storefronts of the Kaufland Seller API: de, cz, sk, pl, at, fr, it, es and nl. You pick one per account on the Connection page; currency and product data language follow it. Which of them you may actually sell in depends on your seller contract with Kaufland.

Does it send invoices?

Not in version 1.0. The buyer's billing data is imported into the OpenCart order.

Does it need a webhook?

No. Push notifications are optional; the scheduled job reads orders and returns on every sync.

Is it endorsed by Kaufland?

No. It uses the public Kaufland Marketplace Seller API under your own seller account.

Does it send data to Kavio Labs?

No. The extension talks to Kaufland only. The license check sends your domain name to the Kavio Labs license server once a day (Kavio Labs licence).

What happens when Kaufland is down?

Jobs fail, wait and are retried automatically (5 minutes up to 12 hours). Nothing is lost and nothing is sent twice.

What happens when the license expires?

New work stops (no stock and price push, no import of new orders). The admin pages stay open and work already under way is finished. A new installation works for 14 days without a key.

How do I get updates?

Upload the new package in Extensions > Installer. See Installation.

How do I get support?

Write to us from your purchase page.