ℹ️This change was deployed on 02.07.2025.
A new property will be added to OfferMarketPrice, namely buybox_scope which returns a new enum.
It will return INSTANCE_GRADING_BATTERY_CONDITION if the offer won the buybox state for instance grading battery combination and will be empty if it won whole instance-grading.
In addition, filtering will be introduced as follows:
market_price_buybox_scope will be introduced in
- ListMarketOffersRequest
- ListMarketOffersByOfferRequest
The filter will be of type OfferBuyboxScopeFilter and will accept operations:
- any_of
- none_of
Behaviour Change
Given that new battery instances usually priced higher, historically they were shown as "ELIGIBLE". Even when they were the most competitive offer for the new battery instance. As of the change, the state will be shown as 'WON' with additional information being that buybox_scope is INSTANCE_GRADING_BATTERY_CONDITION.
In case whole instance grade buybox is won, the state will be shown as 'WON' and buybox_scope will be empty.
In addition, there will be a change to how site_market_suggested_offer_price and suggested_offer_price will function in case battery condition is OPTIMAL and buybox_scope is INSTANCE_GRADING_BATTERY_CONDITION:
- the prices will be taking into account any battery condition so changing the price will let the offer compete with NEW battery offers that are priced lower than existing OPTIMAL battery offer
You can find some examples here:
Example of a market offer that won the full buybox:
{
"offer_id": "1361",
"market_code": "at",
"market_name": "Austria",
"is_site_market": true,
"is_calculated": true,
"currency_code": "EUR",
"price": "333.00",
"min_price": "444.00",
"site_market_currency_code": "EUR",
"site_market_price": "333.00",
"site_market_min_price": "444.00",
"visibility": "FULL",
"instance_buybox_state": "WON",
"battery_condition": "OPTIMAL",
}
Example of a market offer that won the battery condition buybox:
{
"offer_id": "1361",
"market_code": "at",
"market_name": "Austria",
"is_site_market": true,
"is_calculated": true,
"currency_code": "EUR",
"price": "333.00",
"min_price": "444.00",
"site_market_currency_code": "EUR",
"site_market_price": "333.00",
"site_market_min_price": "444.00",
"visibility": "FULL",
"instance_buybox_state": "WON",
"battery_condition": "NEW",
"buybox_scope": "INSTANCE_GRADING_BATTERY_CONDITION"
}
In order to find all won offers you can use the filter as before:
{
.
.
.
"filter": {
"market_price_instance_buybox_state": {
"any_of": [
"WON"
],
},
}
}
In order to find offers that won only the battery instance buybox you can use the following filter in the ListMarketOffer and ListMarketOfferByOffer requests :
{
.
.
.
"filter": {
"market_price_instance_buybox_state": {
"any_of": [
"WON"
],
},
"market_price_buybox_scope": {
"any_of": [
"INSTANCE_GRADING_BATTERY_CONDITION"
],
},
}
}
In order to find offers that won the whole instance buybox only:
{
.
.
.
"filter": {
"market_price_instance_buybox_state": {
"any_of": [
"WON"
],
},
"market_price_buybox_scope": {
"none_of": [
"INSTANCE_GRADING_BATTERY_CONDITION"
],
},
}
}
In case optimal battery offer is winning instance grade battery buybox only, the following response for ListMarketOffer is expected where suggested_offer_price and suggested_offer_price can be used to win instance grade buybox:
{
"market_offers": [
{
"id": {
"offer_id": "1361",
"market_code":"at",
},
"created_at": "2025-06-27T08:42:03.988Z",
"instance_id": "1234",
"state": "OK",
"sku": "SKU123",
"grading": "A",
"warranty": "12M",
"stock": 10,
"shipping_profile_id": "1",
"shipping_profile_name": "Premium",
"taxation": "GROSS",
"reference_currency_code": "EUR",
"reference_price": "100",
"reference_min_price": "100",
"market_price": {
"offer_id": "1361",
"market_code": "de",
"market_name": "Germany",
"is_site_market": true,
"is_calculated": true,
"currency_code": "EUR",
"price": "99",
"min_price": "99",
"site_market_currency_code": "EUR",
"site_market_price": "99",
"site_market_min_price": "99",
"instance_buybox_state": "WON",
"buybox_scope": "INSTANCE_GRADING_BATTERY_CONDITION",
"instance_buybox_info": {
"site_market_competitor_price": "97",
"site_market_suggested_offer_price": "97",
"site_market_suggested_offer_price_diff": "2",
"suggested_offer_price": "97",
"suggested_offer_price_diff": "3"
}
}
}
],
"has_more": true
}