Push Notifications

The Push Notifications feature allows you to be notified immediately whenever certain events happen on the Kaufland marketplace, e.g. when a customer buys something from you. When an event occurs on the Kaufland marketplace servers, an HTTP POST request is sent to a callback URL that you define when you subscribe to the event. This makes your integration with the Kaufland marketplace more immediate and more efficient, since you are notified right away when an event occurs, instead of having to periodically poll the API endpoints. Note that the notification does not contain the changed data, instead it just tells you that the data at a specific endpoint has changed. You will still need to do an API request to the specified endpoint to retrieve the new data.

To subscribe to an event, you need to send an HTTP POST request to the /subscriptions/ endpoint. As a query parameter you should provide the storefront for which you want to receive push notifications - for example ?storefront=de (see the Storefront section for more details and currently-supported storefronts). In the body, you must send a JSON object with the following properties:

callback_url - A publicly-accessible URL that will receive a POST request for each event notification with a maximum length of 255 characters.
fallback_email - An email address that will receive an email if we can’t reach the callback URL for an extended period of time and we disable your subscription.
event_name - The name of the event you are subscribing to. See the Events section for all currently-supported events.

Example:

POST https://sellerapi.kaufland.com/v2/subscriptions?storefront=de

Request body:

{
	"callback_url": "https://example.com/hm_notifications.php",
	"fallback_email": "[email protected]",
	"event_name": "order_new"
}

Response body:

{
   "data": {
     "id_subscription": 11011,
     "callback_url": "https://example.com/hm_notifications.php",
     "fallback_email": "[email protected]",
     "event_name": "order_new",
     "is_active": true,
     "storefront": "de"
   }
}

Callback URL Verification

When you subscribe to a new event, or modify an existing subscription, the Kaufland marketplace server will immediately make an HTTP GET request to your callback URL, in order to verify that the callback server is configured correctly. A query string with the following parameters will be sent with the request:

mode - The string "subscribe".
challenge - A random string.

When your server receives this request, it must respond with a response body that contains only the challenge value. This confirms that this server is configured to accept callbacks and is working correctly.

Example request:

GET https://example.com/hm_notifications.php?mode=subscribe&challenge=dd4aeae00158dc91de38585805ad7410d79b4237f4928e6e466934284f638430

Correct response body:

dd4aeae00158dc91de38585805ad7410d79b4237f4928e6e466934284f638430

Here is the source code for a PHP script that will correctly answer the verification request:

<?php

if ('GET' == $_SERVER['REQUEST_METHOD']) {
	if (isset($_GET['mode']) && 'subscribe' == $_GET['mode']) {
		echo $_GET['challenge'];
		exit;
	}
}

Note: All push notification requests, including the verification request, have a 15 second timeout, so your server must always respond within this time frame.

Notification Requests

Once you have subscribed to an event, the Kaufland marketplace servers will do an HTTP POST request to your callback URL whenever that event occurs. The request will contain the following headers:

Shop-Timestamp - The unix timestamp of the time when the event occurred.
Shop-Signature - A MAC signature for the request. This signature is generated using your key_secret, with the same function that you use to sign your API requests. This is a security feature which allows you to verify that the request is really coming from the Kaufland marketplace, since only you and the Kaufland marketplace have your key_secret. The signature generation function is described on the REST API page. When you receive a notification, you should generate a signature for the request and verify that it is the same as the one specified in the Shop-Signature header.

The notification request will also contain a JSON object in the body, with the following fields:

event_name - The name of the event. This is the same as the event_name you specified when you subscribed to the event.
id_message - A unique ID for the event occurrence. If the request is a retry because of a problem with the callback server, this ID will be the same as one in a previous request, otherwise it will be globally unique. See the Callback URL Unreachable section for more information about notification retries.
resource - The URL of the resource that changed.
storefront - The storefront where event happened.
payload - For certain events we provide all relevant data for the event in the field payload. Such events are all "item_unit" related ones - "item_unit_new", "item_unit_changed", "item_unit_deleted", etc. For the rest of the events that do not support the feature the field will remain empty.

Here is an example notification request:

POST https://example.com/hm_notifications.php

Request headers:

Shop-Timestamp 1432815691
Shop-Signature c57523ff08413a7eaf88447ba2405c0632fbefecff7b3426d94fd1c4b7482caa

Request body without payload:

{
	"event_name": "order_new",
	"resource": "/orders/123456789/",
	"id_message": "393b6341da2bbeb7bdb27c579fe4b4eb",
	"storefront": "de",
	"payload": []
}

Request body with payload:

{
	"event_name": "item_unit_changed",
	"resource": "/units/123456789/",
	"id_message": "393b6341da2bbeb7bdb27c579fe4b4eb",
	"storefront": "de",
	"payload": {
	    "id_unit":123456789,
	    "id_item":123456,
	    "condition":"new",
	    "location":"DE",
	    "warehouse":"warehouseId",
	    "amount":1,
	    "price":123,
	    "delivery_time":"b",
	    "delivery_time_min":2,
	    "delivery_time_max":3,
	    "shipping_group":"Shipping Group",
	    "note":"",
	    "reference_price":0,
	    "seller":{
	        "pseudonym":"test"
	    },
	    "shipping_rate":0,
	    "date_inserted":"2024-12-11T10:44:21Z",
	    "date_lastchange":"2025-06-23T09:14:12Z",
	    "listing_price":123,
	    "minimum_price":123,
	    "id_offer":"test",
	    "manufacturer_guarantee_years":2,
	    "item":{
	        "id_item":123456,
	        "title":"Apple iPhone 12 mini 64GB Schwarz",
	        "eans":["0194252013212","194252013212","0194252012925"],
	        "id_category":34401,
	        "main_picture":"https://media.cdn.kaufland.de/product-images/2048x2048/7ddfbf37e8c5d3137179e1361c432246.jpg",
	        "manufacturer":"Apple",
	        "url":"https://www.kaufland.de/product/362524873/",
	        "real_mgb_article_number":"",
	        "age_rating":0,
	        "is_valid":true,
	        "dangerous_goods_li_shipping":null,
	        "danger_label_9A":null
	    }
	}
}

Note: manufacturer_guarantee_years is included in the payload only when a value has been set. It is omitted entirely when no manufacturer guarantee is configured for the unit.

Your callback server must return one of the following HTTP status codes within 5 seconds to acknowledge the notification: 200 OK, 201 Created, 202 Accepted, or 204 No Content. The body of the response can be empty and no response headers are required. If the notification request times out, or the response’s status code is anything other than the accepted ones listed above, the system will assume that the notification was not processed, and will queue it to be retried later. See the Callback URL Unreachable section for details about notification retries.

In order to stay under the timeout limit, we recommend using a message broker or job queue like RabbitMQ, NSQ, Gearman, IronMQ or many others. This allows you to queue the event and respond to the notification request immediately. Then, a background worker can do the API request to get the current resource data and do whatever actions are needed to handle the event in your system.

Callback URL Unreachable

Your callback URL should always be available to receive notifications, 24/7. However, we understand that no one has perfect uptime, so if your server is down or a notification request times out, we will retry the notification at increasing intervals for about 12 hours. Each notification always includes an id_message in the body, which contains a unique ID for the event occurrence. Each retry of the notification will always contain the same id_message, so you can tell if two notifications are repeats of the same event, or if they are for two separate occurrences.

If your server comes back online within 12 hours, you will receive all notifications for all events that occurred while the server was down, but not immediately, and not necessarily in the order they occurred. Each time a notification request is unsuccessful, we queue it to be retried, but with an increasing interval between retries. For example, if the first notification attempt fails, we will retry the request after one minute. However, after several failures, we wait 15, 30 or 60 minutes between retries. This means that a notification that failed its first request one minute before your server comes back online will be delivered again right away, but other notifications could take up to one hour to arrive.

If your server is offline for more than 12 hours, we will disable your push notification subscription and send an email to the address specified as the fallback_email when you subscribed to the event. Once your server is ready to receive notifications again, you can re-enable the subscription with a PATCH request to the subscription’s API endpoint. However, events that occurred while your subscription was disabled are lost. You must query the corresponding API endpoint to get all resources that changed during the downtime.

Retrieving Current Subscriptions

You can retrieve your current event subscriptions by sending an HTTP GET request to the /subscriptions/ endpoint. You can optionally specify the event_name and storefront query parameters to filter subscriptions by event name or storefront.

Example:

GET https://sellerapi.kaufland.com/v2/subscriptions

Response body:

[
	{
		"id_subscription": 37,
		"callback_url": "https://example.com/hm_notifications.php",
		"fallback_email": "[email protected]",
		"event_name": "order_new",
		"is_active": true
		"storefront": "de"
	}
]

Modifying a Subscription

To update a subscription you need to send an HTTP PATCH request to the /subscriptions/{id_subscription}/ endpoint and supply the same callback_url, fallback_email, event_name and storefront information as in the subscription creation request. Additionally, you must supply an is_active flag to switch the subscription on or off.

Note: Every time you modify the callback URL it will be re-verified by the Kaufland.de Onlineshop servers. You can find more information about the verification process in the Callback URL Verification section.

Example:

PATCH https://sellerapi.kaufland.com/v2/subscriptions/37/

Request body:

{
	"callback_url": "https://example.com/hm_notifications.php",
	"fallback_email": "[email protected]",
	"event_name": "order_new",
	"is_active": false,
	"storefront": "de"
}

Unsubscribing from an Event

To delete a subscription you need to send an HTTP DELETE request to the /subscriptions/{id_subscription}/ endpoint. The subscription will immediately be permanently deleted.

Example:

DELETE https://sellerapi.kaufland.com/v2/subscriptions/37/

Events

Currently we only offer notifications for some events, but we will be adding more soon.

order_new - This event is triggered once each time a customer places an order which includes one or more of your products. If a customer buys 5 products from you in a single order, only 1 order_new event notification will be sent.
order_unit_new - This event is triggered each time one of your units is ordered. If a customer buys 5 products from you in a single order, 5 separate order_unit_new notifications will be sent.
order_unit_status_changed - This event is triggered each time when the status of one of your units has been changed.
item_changed - This event is triggered each time when a product has changed.
category_changed - This event is triggered each time a category has changed.
return_new - This event is triggered each time a customer starts a return process.
return_status_changed - This event is triggered each time when the status of a customer return has been changed.
return_unit_status_changed - This event is triggered each time when the status of a customer return unit has been changed.
item_unit_new - This event is triggered each time when a new unit for a given Product has been created. Information about the unit will be sent in the field payload.
item_unit_changed - This event is triggered each time when one of the adjustable properties of a unit has been changed. Information about the unit will be sent in the field payload.
item_unit_deleted - This event is triggered each time a unit has been deleted and cannot be sold anymore. Information about the unit will be sent in the field payload.
item_unit_out_of_stock - This event is triggered each time when a unit is out of stock (amount = 0). Information about the unit will be sent in the field payload.
item_unit_not_available - This event is triggered each time when a unit is set from available to onhold, which prevents it from being sold until it is set to available again. Information about the unit will be sent in the field payload.
item_unit_available - This event is triggered each time when a unit is set from onhold to available, so it can be sold again. Information about the unit will be sent in the field payload.
buy_box_changed - This event is triggered when the Buy Box status changes on a product where you have a ranking, including winning or losing the #1 position, the current winner updating their price, or your own price changing. See the Buy Box Changed Event section below for detailed information about the notification payload and behavior.

Buy Box Changed Event

The buy_box_changed event notifies you about Buy Box changes on products where you have an active offer. This event is triggered when you win or lose the #1 Buy Box position, when the current winner changes their price, or when your own price changes, allowing you to respond quickly to competitive pricing changes.

When This Event is Triggered

You will receive a notification when:

You win the #1 Buy Box position on a product
You lose the #1 Buy Box position on a product
The current Buy Box winner changes their price on a product where you have a ranking. Even if you don't win or lose the #1 position, you'll be notified of the winner's price change so you can adjust your strategy
Your own price changes on a product where you have a ranking, even if the Buy Box winner stays the same. This lets you confirm your price update was picked up and see how it affects your position

Important Behavioral Notes

Debounced Notifications: Buy Box changes are debounced to ensure you receive stable, actionable information. When rapid price changes occur on the same product, the system waits for the Buy Box to stabilize before sending a notification. This means notifications are not real-time and may be delayed by several minutes. The notification you receive will reflect the most recent stable state of the Buy Box.

Best-Effort Delivery: During periods of high marketplace activity, the notification queue may experience a backlog. In such cases, older notifications may be dropped to prioritize more recent changes. While rare, this means some Buy Box changes may not trigger a notification.

Event Scope

Condition: This event is available for products with condition = "new". Other conditions (used, refurbished, etc.) are not included.
Subscription Required: You must have an active subscription to the buy_box_changed event for the relevant storefront to receive notifications.

Notification Payload

Privacy-Aware Notifications: Each notification is personalized for privacy. You will see the top-ranked offers (up to 10), but competitor offer identifiers (id_unit, id_offer) are hidden. Only your own offers include these identifiers, allowing you to identify which of your units is competing while respecting competitor privacy.

The notification request body contains the following fields:

event_name - string
Always "buy_box_changed" for this event.
resource - string
The API endpoint to query for current Buy Box state. Format: /buybox?id_product={id}&condition={condition}
id_message - string
A unique identifier for this notification. Retries of the same event will have the same id_message.
storefront - string
The storefront where this change occurred (e.g., "de", "cz").
payload - object
Contains detailed information about the Buy Box change:
- buy_box_change - string
  Indicates the type of change for you: "won" (you won the Buy Box), "lost" (you lost the Buy Box), or "changed" (the winner kept the Buy Box but something shifted - either the winner's price changed, or your own price changed).
- id_product - integer
  The internal Kaufland product ID.
- condition - string
  The product condition. Always "new".
- timestamp - string (ISO 8601)
  The timestamp when this Buy Box change was recorded.
- eans - array of strings
  A list of EAN codes associated with this product.
- winner_offer - object
  The current Buy Box winner's offer. See Offer Structure below for field details.
- seller_offer - object
  Your offer (the notification recipient's offer). See Offer Structure below for field details. Additionally includes id_unit, id_offer, and optionally target_price.
- offers - array of objects
  A ranked list of the top competing offers (up to 10). Each offer follows the Offer Structure below

Offer Structure

Each offer object (used in winner_offer, seller_offer, and the offers array) contains the following fields:

seller - object
Information about the seller:
- pseudonym - string - The seller's display name
prices - object
Price information with currency:
- total_price - object - Contains amount (integer, minor unit of the currency) and currency_code (string, e.g., "EUR"). This is the full price including shipping
- sales_price - object - Product price excluding shipping, same structure as total_price
- shipping_cost - object - Shipping cost, same structure as total_price
- target_price - object (optional) - Only present in seller_offer when buy_box_change is "lost" or "changed". Provides a suggested sales price that may help you compete for the Buy Box. Contains amount and currency_code
delivery_time - object
Estimated delivery timeframe:
- min - integer or null - Minimum delivery time in days
- max - integer or null - Maximum delivery time in days
rank - integer
Position in the Buy Box ranking, where 1 = winner. Present in seller_offer (your own rank) and in each entry of the offers array
id_unit - integer - (Only for your offers)
Your internal unit ID. Present in seller_offer and in offers array entries that belong to you
id_offer - string - (Only for your offers)
Your SKU/offer ID. Present in seller_offer and in offers array entries that belong to you

Example Notification: Seller Wins Buy Box

This example shows a notification when you win the #1 Buy Box position. Notice that buy_box_change is "won" and your offer appears as seller_offer while the previous winner is shown in winner_offer (which now refers to the current state where you are the winner).

POST https://example.com/webhooks/

Request headers:

Shop-Timestamp 1735819234
Shop-Signature a3f8d2c9e1b4a7f6d3c8e9a2b5f7d4e6c9a3b8f2d7e4a9c6b3f8d2e7a4c9b6f3

Request body:

{
	"event_name": "buy_box_changed",
	"resource": "/buybox?id_product=362524873&condition=new",
	"id_message": "b8f3d2e7a4c9b6f3a8d2c9e1b4a7f6d3",
	"storefront": "de",
	"payload": {
		"buy_box_change": "won",
		"id_product": 362524873,
		"condition": "new",
		"timestamp": "2026-07-02T16:27:14+02:00",
		"eans": ["0194252013212", "194252013212"],
		"winner_offer": {
			"seller": {
				"pseudonym": "My Shop"
			},
			"prices": {
				"total_price": {
					"amount": 90400,
					"currency_code": "EUR"
				},
				"sales_price": {
					"amount": 89900,
					"currency_code": "EUR"
				},
				"shipping_cost": {
					"amount": 500,
					"currency_code": "EUR"
				}
			},
			"delivery_time": {
				"min": 1,
				"max": 3
			}
		},
		"seller_offer": {
			"rank": 1,
			"id_unit": 28374940,
			"id_offer": "MY-SKU-12345",
			"seller": {
				"pseudonym": "My Shop"
			},
			"prices": {
				"total_price": {
					"amount": 90400,
					"currency_code": "EUR"
				},
				"sales_price": {
					"amount": 89900,
					"currency_code": "EUR"
				},
				"shipping_cost": {
					"amount": 500,
					"currency_code": "EUR"
				}
			},
			"delivery_time": {
				"min": 1,
				"max": 3
			}
		},
		"offers": [
			{
				"rank": 1,
				"id_unit": 28374940,
				"id_offer": "MY-SKU-12345",
				"seller": {
					"pseudonym": "My Shop"
				},
				"prices": {
					"total_price": {
						"amount": 90400,
						"currency_code": "EUR"
					},
					"sales_price": {
						"amount": 89900,
						"currency_code": "EUR"
					},
					"shipping_cost": {
						"amount": 500,
						"currency_code": "EUR"
					}
				},
				"delivery_time": {
					"min": 1,
					"max": 3
				}
			},
			{
				"rank": 2,
				"seller": {
					"pseudonym": "Competitor Shop"
				},
				"prices": {
					"total_price": {
						"amount": 90600,
						"currency_code": "EUR"
					},
					"sales_price": {
						"amount": 90000,
						"currency_code": "EUR"
					},
					"shipping_cost": {
						"amount": 600,
						"currency_code": "EUR"
					}
				},
				"delivery_time": {
					"min": 2,
					"max": 4
				}
			}
		]
	}
}

In this example, you have won the Buy Box. Both winner_offer and seller_offer refer to your offer since you are now the winner. The offers array shows you at rank 1 (with id_unit and id_offer included) and a competitor at rank 2 (without identifiers for privacy). Note that target_price is not present when you win.

Example Notification: Seller Loses Buy Box

This example shows a notification when you lose the #1 Buy Box position. The buy_box_change field is "lost", winner_offer shows the competitor who now has the Buy Box, and seller_offer shows your offer.

POST https://example.com/webhooks/

Request headers:

Shop-Timestamp 1735820156
Shop-Signature c9b6f3a8d2c9e1b4a7f6d3c8e9a2b5f7d4e6c9a3b8f2d7e4a9c6b3f8d2e7a4

Request body:

{
	"event_name": "buy_box_changed",
	"resource": "/buybox?id_product=362524873&condition=new",
	"id_message": "d7e4a9c6b3f8d2e7a4c9b6f3a8d2c9e1",
	"storefront": "de",
	"payload": {
		"buy_box_change": "lost",
		"id_product": 362524873,
		"condition": "new",
		"timestamp": "2026-07-02T16:42:36+02:00",
		"eans": ["0194252013212", "194252013212"],
		"winner_offer": {
			"seller": {
				"pseudonym": "Competitor Shop"
			},
			"prices": {
				"total_price": {
					"amount": 90100,
					"currency_code": "EUR"
				},
				"sales_price": {
					"amount": 89500,
					"currency_code": "EUR"
				},
				"shipping_cost": {
					"amount": 600,
					"currency_code": "EUR"
				}
			},
			"delivery_time": {
				"min": 2,
				"max": 4
			}
		},
		"seller_offer": {
			"rank": 2,
			"id_unit": 28374940,
			"id_offer": "MY-SKU-12345",
			"seller": {
				"pseudonym": "My Shop"
			},
			"prices": {
				"total_price": {
					"amount": 90400,
					"currency_code": "EUR"
				},
				"sales_price": {
					"amount": 89900,
					"currency_code": "EUR"
				},
				"shipping_cost": {
					"amount": 500,
					"currency_code": "EUR"
				},
				"target_price": {
					"amount": 89400,
					"currency_code": "EUR"
				}
			},
			"delivery_time": {
				"min": 1,
				"max": 3
			}
		},
		"offers": [
			{
				"rank": 1,
				"seller": {
					"pseudonym": "Competitor Shop"
				},
				"prices": {
					"total_price": {
						"amount": 90100,
						"currency_code": "EUR"
					},
					"sales_price": {
						"amount": 89500,
						"currency_code": "EUR"
					},
					"shipping_cost": {
						"amount": 600,
						"currency_code": "EUR"
					}
				},
				"delivery_time": {
					"min": 2,
					"max": 4
				}
			},
			{
				"rank": 2,
				"id_unit": 28374940,
				"id_offer": "MY-SKU-12345",
				"seller": {
					"pseudonym": "My Shop"
				},
				"prices": {
					"total_price": {
						"amount": 90400,
						"currency_code": "EUR"
					},
					"sales_price": {
						"amount": 89900,
						"currency_code": "EUR"
					},
					"shipping_cost": {
						"amount": 500,
						"currency_code": "EUR"
					}
				},
				"delivery_time": {
					"min": 1,
					"max": 3
				}
			}
		]
	}
}

In this example, you have lost the Buy Box to a competitor who lowered their total price to €901.00 compared to your €904.00. The target_price field (€894.00) provides a suggested sales price that may help you compete for the Buy Box. The offers array shows the top 2 offers with ranks, where you are #2. Note that the competitor's offer (rank 1) does not include id_unit or id_offer fields for privacy.

Example Notification: Buy Box Changed (Neither Won Nor Lost)

This example shows a notification when neither you nor the current winner takes over the #1 position, but something still shifted - here, your own price changed while the competitor kept the Buy Box. The buy_box_change field is "changed", winner_offer still shows the same competitor as before, and seller_offer shows your updated offer at rank 2.

POST https://example.com/webhooks/

Request headers:

Shop-Timestamp 1735821342
Shop-Signature e1b4a7f6d3c8e9a2b5f7d4e6c9a3b8f2d7e4a9c6b3f8d2e7a4c9b6f3a3f8d2c9

Request body:

{
	"event_name": "buy_box_changed",
	"resource": "/buybox?id_product=362524873&condition=new",
	"id_message": "a4c9b6f3a8d2c9e1b4a7f6d3c8e9a2b5",
	"storefront": "de",
	"payload": {
		"buy_box_change": "changed",
		"id_product": 362524873,
		"condition": "new",
		"timestamp": "2026-07-02T17:05:42+02:00",
		"eans": ["0194252013212", "194252013212"],
		"winner_offer": {
			"seller": {
				"pseudonym": "Competitor Shop"
			},
			"prices": {
				"total_price": {
					"amount": 90100,
					"currency_code": "EUR"
				},
				"sales_price": {
					"amount": 89500,
					"currency_code": "EUR"
				},
				"shipping_cost": {
					"amount": 600,
					"currency_code": "EUR"
				}
			},
			"delivery_time": {
				"min": 2,
				"max": 4
			}
		},
		"seller_offer": {
			"rank": 2,
			"id_unit": 28374940,
			"id_offer": "MY-SKU-12345",
			"seller": {
				"pseudonym": "My Shop"
			},
			"prices": {
				"total_price": {
					"amount": 90200,
					"currency_code": "EUR"
				},
				"sales_price": {
					"amount": 89700,
					"currency_code": "EUR"
				},
				"shipping_cost": {
					"amount": 500,
					"currency_code": "EUR"
				},
				"target_price": {
					"amount": 89400,
					"currency_code": "EUR"
				}
			},
			"delivery_time": {
				"min": 1,
				"max": 3
			}
		},
		"offers": [
			{
				"rank": 1,
				"seller": {
					"pseudonym": "Competitor Shop"
				},
				"prices": {
					"total_price": {
						"amount": 90100,
						"currency_code": "EUR"
					},
					"sales_price": {
						"amount": 89500,
						"currency_code": "EUR"
					},
					"shipping_cost": {
						"amount": 600,
						"currency_code": "EUR"
					}
				},
				"delivery_time": {
					"min": 2,
					"max": 4
				}
			},
			{
				"rank": 2,
				"id_unit": 28374940,
				"id_offer": "MY-SKU-12345",
				"seller": {
					"pseudonym": "My Shop"
				},
				"prices": {
					"total_price": {
						"amount": 90200,
						"currency_code": "EUR"
					},
					"sales_price": {
						"amount": 89700,
						"currency_code": "EUR"
					},
					"shipping_cost": {
						"amount": 500,
						"currency_code": "EUR"
					}
				},
				"delivery_time": {
					"min": 1,
					"max": 3
				}
			}
		]
	}
}

In this example, you lowered your total price from €904.00 to €902.00, but it still wasn't enough to overtake the competitor's €901.00, so the Buy Box winner is unchanged. You still get notified — with buy_box_change: "changed" — so you can confirm your price update was picked up and see your new rank (2) relative to the winner. Note that seller_offer.rank reflects your own position even though you are not present in winner_offer.

How to Use This Event

When you receive a buy_box_changed notification:

Check the change type: Look at the buy_box_change field to understand what happened: "won", "lost", or "changed"
Review the competitive landscape: Use the offers array to see the top-ranked offers (up to 10) with their ranks, prices, and delivery times. Your own offers will include id_unit and id_offer fields
Compare key offers: Review winner_offer (current #1) and seller_offer (your offer) for quick comparison
Use target price guidance (if you lost): When buy_box_change is "lost" or "changed", check seller_offer.prices.target_price for suggested pricing that may help you compete for the Buy Box
Understand pricing: All prices are in the minor unit of the currency (e.g., 90400 = €904.00) and include the currency_code
Identify your unit: Use the id_unit and id_offer from seller_offer to identify which of your units is affected
Take action: Adjust your pricing or fulfillment strategy based on the competitive data and target price guidance

Storefront

You are able to get push notifications on different callback URLs based on the storefronts, even for the same event. If you subscribed to de - german storefront, you will get notifications about events that have happened only for this storefront. You need to create notifications individually per storefront if you want to be notified for events happening on all of them.

Push Notifications

Subscribing to Notifications for an Event

Callback URL Verification

Notification Requests

Callback URL Unreachable

Retrieving Current Subscriptions

Modifying a Subscription

Unsubscribing from an Event

Events

Buy Box Changed Event

When This Event is Triggered

Important Behavioral Notes

Event Scope

Notification Payload

Offer Structure

Example Notification: Seller Wins Buy Box

Example Notification: Seller Loses Buy Box

Example Notification: Buy Box Changed (Neither Won Nor Lost)

How to Use This Event

Storefront