Kaufland Seller API v2: Migrating an Older Integration
Is Kaufland API v1 shutting down? What changed in Seller API v2 (signing, storefronts, units, order units) and a step-by-step plan to migrate safely.
- Written by
- Md AshikSenior Software Engineer, Artisan Dojo
- Published
- Reading time
- 7 min read
Quick summary30-second read
- Kaufland Seller API v2 has been the current API since 2022, and integrators such as Channable have dropped legacy v1 support.
- We found no official Kaufland shutdown date for v1, but Channable announced removing legacy Kaufland support on March 1, 2026.
- v2 requests are signed with an HMAC-SHA256 signature sent in Shop-Client-Key, Shop-Timestamp and Shop-Signature headers.
- v2 uses storefronts, technical IDs for warehouses and shipping groups, handling time, and prices in integer cents.
- Migrate one flow at a time after a read-only parallel run, and keep a scheduled sync alongside push notifications.
The current Kaufland API is the Marketplace Seller API version 2, at sellerapi.kaufland.com/v2. Kaufland released it in 2022 as the major successor to the older v1 API, and integrators have been dropping v1 support since. If your integration still uses v1 endpoints, old request headers or a legacy feed, plan a migration now: Channable, for example, announced it would drop legacy Kaufland support on March 1, 2026.
Below: how to tell which version you are on, what changed, and how to switch without losing orders. For the basics of a Kaufland integration (units, storefronts, order units), start with how to connect Kaufland to your ERP.
Is the Kaufland API v1 being shut down?
Here is what we could verify, and what we could not:
- v2 is the current API. Kaufland's release log lists version 2.0.0 as the "major release of API V2" and documents the changes from v1. New features since then, such as new push notification events and volume discount endpoints, are documented for v2.
- v1 is the legacy version. Kaufland's release log introduces 2.0.0 as the major release of API v2 and points v1 users to the list of changes.
- Integrators have dropped legacy support. Channable announced in January 2026 that it would remove its legacy Kaufland integration (feed plus Kaufland API v1) on March 1, 2026, and asked users to move to its Kaufland V2 channel. At least one extension vendor, CedCommerce, has written that the old v1 API was fully sunset starting March 2023.
- We found no official Kaufland shutdown date in the v2 release log or documentation. We are not going to invent one.
In practice, the direction matters more than the date: an integration that still depends on the old interface is running on borrowed time.
How do I know which Kaufland API version my integration uses?
Check the code or ask your vendor these questions:
- Which base URL does it call? v2 requests go to
https://sellerapi.kaufland.com/v2/. Anything else, such as an oldkaufland.de/api/v1path, is legacy. - Which headers does it send? v2 requires
Shop-Client-Key,Shop-Timestamp,Shop-Signature,AcceptandUser-Agent. Integrators report that v1 used headers prefixed withHm-instead, for exampleHm-Signature. - Does it send a storefront? v2 ties units, subscriptions and reports to a
storefrontparameter, such asde. Code that never sets one is probably old. - Does it send warehouse and shipping group names? In v2 you send technical IDs (
id_warehouse,id_shipping_group). Names point to v1 logic.
Kaufland API v1 vs v2: what changed?
The v2 column below comes from Kaufland's Seller API documentation. The v1 column is based on integrator documentation from BeezUP and CedCommerce, since Kaufland's v1 docs are no longer the reference.
| Area | Legacy v1 (as reported by integrators) | Seller API v2 (Kaufland docs) |
|---|---|---|
| Base URL | Old Kaufland.de API | https://sellerapi.kaufland.com/v2/ |
| Auth headers | Hm-Client-Key, Hm-Timestamp, Hm-Signature | Shop-Client-Key, Shop-Timestamp, Shop-Signature, plus User-Agent |
| Country | No storefront parameter | storefront parameter, values from /info/storefront |
| Warehouse | warehouse by name | id_warehouse by technical ID |
| Shipping group | shipping_group by name | id_shipping_group by technical ID |
| Delivery time | delivery_time_min / delivery_time_max | handling_time in working days; Kaufland adds transport time per carrier |
| Order shipping method | z-Ships_in_x-y_days/weeks | Ships_in_x-y_days |
| Timestamps | Older formats | ISO 8601 throughout |
How does v2 authentication work?
Each v2 request is signed with an HMAC-SHA256 signature, hex-encoded. The string to sign is the HTTP method in uppercase, the full URI (including https:// and the domain), the request body (empty string if none) and the Unix timestamp in seconds, joined by newlines. You sign it with your secret key and send the result in Shop-Signature, together with Shop-Client-Key and Shop-Timestamp.
Details that cause failed requests:
- Use the secret key as a plain string. Kaufland's docs warn not to hex-decode it.
- Keep your clock in sync. The timestamp must be within five minutes of Kaufland's server time.
- Sign the exact URI you send, including query parameters such as
storefront. - Set a real
User-Agent. Software vendors send their product name; in-house integrations useInhouse_development.
Compare your output with the signature calculator in Kaufland's docs before debugging anything else.
Step-by-step: how to migrate a Kaufland integration to v2
- Inventory what the integration does. List every call and file it uses: product data, unit creation, stock and price updates, order import, shipping confirmation, cancellations, returns, reports. Note how often each runs and which ERP or WMS fields feed it.
- Map each flow to v2. Find the matching v2 endpoint for each flow, for example
POST /units/andPOST /units/bulkfor offers,GET /order-unitsfor orders, andPATCH /order-units/{id}/sendfor shipping. Note any fields that changed type, such as IDs instead of names. - Rebuild authentication and the HTTP client. Implement the v2 signing, retries for 429 and 5xx responses, and pagination. Do this once in a shared client, not per flow.
- Decide how to handle storefronts. List the storefronts you sell on. Decide whether stock is shared across them (units with the same
id_offershare warehouse and quantity) and whether prices differ per country (prices are not synced). - Test with real data in a safe place. Kaufland offers a playground environment. The "Try it out" feature on the live endpoint docs changes real data, so do not test there.
- Run old and new in parallel, read-only first. Let the v2 integration fetch orders and units and compare them with what the old integration imported, without writing anything to Kaufland or the ERP.
- Cut over one flow at a time. Start with stock and price, then order import, then shipping confirmations and returns. Switch off the old flow at the moment the new one takes over, so nothing is sent twice.
- Monitor closely after cutover. Watch for missing orders, rejected units and late shipping confirmations for the first weeks. Our marketplace ERP integration checklist lists what to monitor.
Top tip
Keep the old integration's order IDs in a lookup table during the parallel run. If both systems import the same order unit, you can spot it immediately instead of finding a duplicate shipment a week later.
What data mapping problems should I expect?
Most migration effort is in the data, not the HTTP calls:
- EAN matching. Units identify the product by
id_product,eanor both. Clean up missing or reused EANs before migrating, or units will be rejected. - Units and
id_offer. APOST /units/updates an existing unit if the storefront andid_offermatch (or, withoutid_offer, the condition). Otherwise it creates a new one. You cannot changeid_productorid_offeron an existing unit; delete and recreate it instead. - Prices in cents. v2 expects prices as integers in cents of the storefront currency (EUR, CZK or PLN). A missing conversion can list an item at a hundredth of its price.
- Handling time. Replace delivery time ranges with handling time in working days, and remove any transport time you added yourself.
- Order units. Each item is a separate order unit. Group them by
id_orderif your ERP wants one order with several lines, and use the order unit ID as the unique key. - Status mapping. New order units start as
openand move toneed_to_be_sentafter 15 minutes unless the customer cancels. Import fromneed_to_be_sentso you do not ship cancelled items. - Shipping confirmations. Send
carrier_codeandtracking_numbersper order unit. Map your carriers to Kaufland's allowed carrier codes. - Returns. Returns have their own endpoints and return units with accept, reject, repair and clarify actions. Reject and clarify need a message and open a ticket, so do not automate them blindly.
Should I use push notifications in v2?
Yes, alongside a scheduled sync. v2 supports subscriptions: Kaufland sends a POST to your callback URL for events such as order_unit_new, order_unit_status_changed and return_new. Some points to plan for:
- Subscriptions are per storefront. You need one per event and storefront.
- Most notifications only say something changed. You call the API to fetch the data.
- Answer within five seconds. Queue the work and acknowledge immediately.
- Handle retries and gaps. Retries reuse the same
id_message, so you can deduplicate. If your endpoint is down for more than about 12 hours, Kaufland disables the subscription and the missed events are lost.
Common mistakes
- Assuming only the headers changed. IDs, handling time and order fields changed too.
- Forgetting storefronts. Code that works for
desilently does nothing for Austria, Poland or other countries you sell in. - Cutting over everything at once, so a mapping error hits orders, stock and shipping at the same time.
- Running both integrations with write access, causing double stock updates or duplicate shipping confirmations.
- Ignoring HTTP 429. Without backoff, bursts above the rate limit fail silently.
- Relying only on notifications, with no scheduled sync to catch missed events.
Frequently asked questions
Has Kaufland set an official shutdown date for API v1?
We could not find one in Kaufland's current Seller API documentation or release log. v2 has been the current version since 2022, and Channable announced the removal of its v1 support for March 1, 2026. Treat v1 as unsupported and migrate.
What are the rate limits in Kaufland API v2?
Kaufland documents a limit of 111 requests per second per seller, across all endpoints combined. Above that, the API answers with HTTP 429. Very deep pagination on GET /units has a separate, lower limit.
Can I still use CSV files with Kaufland?
Yes. The v2 documentation includes a CSV file interface for product data, inventory and orders. Check that your files follow the current v2 formats rather than an old feed template.
My multichannel tool handles Kaufland. Do I need to do anything?
Check whether your Kaufland channel in that tool is a legacy or V2 channel. In Channable, for example, migrating creates an offer-only channel, and product data needs its own setup.
How long does a Kaufland v2 migration take?
It depends on how many flows the integration covers and how clean your product data is. Stock and price sync alone is a much smaller job than orders, returns and several storefronts.
Need help moving to Kaufland API v2?
We build and maintain Kaufland integrations connected to ERPs and warehouse systems, including migrations of older setups. See our Kaufland API integration service, or our integration maintenance if you want someone to keep it current. Describe your setup below and you will get a reply from the engineer who would do the work.