The BuyBox is a mechanism to determine the best offer for a customer. The offer of the BuyBox winner will be shown as main offer for a product on refurbed. The BuyBox allows merchants to compete for customers on refurbed products. refurbed determines the ranking of the BuyBox by an algorithm that takes many different aspects into account, such as the quality of the products, good inventory management, fast shipping times, and quick response times to customer tickets, to just mention a few.
All services and operations concerning the shipping profiles must be called with OfferService in the URL followed by the command/operation.
E.g.: https://api.refurbed.com/refb.merchant.v1.OfferService/ListOffers
All calls must be done using POST method.
Read (OfferService / MarketOfferService)
refurbed provides BuyBox-related information for your market offers. There you can see for example whether your offer won the BuyBox for a specific market or whether it could win it with a price adjustment. This BuyBox-specific state and information can help you to adjust your market offer min prices and potentially win the BuyBox.
If your market offer is visible, the BuyBox-specific information is divided into the BuyBox state and the BuyBox information.
There are different ways to poll for BuyBox-related information. You can use the ListOffers / GetOffer / BatchGetOffers endpoints of the OfferService to read the BuyBox data for all your offers and markets. Or you can filter for specific SKUs, markets, market offer visibility and/or BuyBox state with the ListMarketOffers / GetMarketOffer / BatchGetMarketOffer endpoints of the MarketOfferService.
If you want to compete effectively for the buybox we suggest to use ListMarketOffers and apply the following filter in the request:
{
"filter": {
"market_price_instance_buybox_state": {
"any_of": [
"ELIGIBLE"
]
}
}
}
This request will only return you market offers that are eligible to win the buybox including suggested prices that you can set in a follow-up batch update call.
⚠️ Polling for all your market offers using the MarketOfferService can quickly add up to too many API requests. We always recommend filtering e.g. like above or for specific SKUs. Please make sure to comply with our rate limits.
Market prices
The market_price gives you information about the specific market offer, whether refurbed has a localized website for the market, whether the market price is calculated by refurbed or set by the seller themselves, and the market-specific price and currency.
If the market price is calculated by refurbed (is_calculated is true), refurbed uses the offer’s reference_price, reference_min_price (if available), and reference_currency_code as reference. Otherwise (is_calculated is false) the price, min price, and currency code that are set by the seller are returned.
If refurbed has a localized website for the market (is_site_market is true) also the currency code, price, and min price in the currency of the site market are shown.
| Field | Description |
|---|---|
| market_code | Code of the market the price is set for. |
| market_name | Name of the market the price is set for. |
| is_site_market | Indicates whether there exists a refurbed website for this market. |
| is_calculated | Indicates whether the price was calculated by a rule or set manually by the seller. |
| currency_code | Market offer currency set by the seller for the market or taken from the offer’s reference currency code. |
| price | Gross price of this market offer. Either set by the seller, or calculated by refurbed based on the reference price. |
| min_price | Optional minimum price for automatic repricing. Either set by the seller, or calculated by refurbed based on the reference min price. |
| site_market_currency_code | Currency of the site market. |
| site_market_price | Price in currency of the site market. Only set for site markets. |
| site_market_min_price | Minimum price in currency of the site market. Only set for site markets. |
Market Offer visibility
With the visibility you can identify which of your market offers is visible on our platform. When a market offer is fully visible, it does not mean that it has won the BuyBox.
| Visibility | Description |
|---|---|
| FULL | Offer is shown to customers. |
| NONE | Offer is not shown to customers (e.g. does not ship into this market, is out of stock, is not verified). |
| LIMITED | Offer was hidden from some pages by refurbed (e.g. because price is higher than refurbed's instance Suggested Retail Price). |
| HIDDEN | Offer was hidden by refurbed (e.g. because because price is higher than refurbed's instance Suggested Retail Price or stock is 0). |
Instance BuyBox state
If a market offer has full or hidden visibility and we have a localized website for that market, then you can see its BuyBox state (instance_buybox_state ). Below you can find a list of these states and their meaning:
| State | Description |
|---|---|
| WON | Offer currently has the BuyBox. |
| SHOULD_WIN | Current offer configuration should win the BuyBox on next refresh. |
| ELIGIBLE | Offer currently does not have the BuyBox but could get it with some adjustments, e.g. in price or shipping time. |
| WON_ELSEWHERE | Offer currently does not have the BuyBox but another offer of this merchant does. |
| INELIGIBLE | Offer cannot reach the BuyBox at this time, e.g. because refurbed's BuyBox protection for this product is enabled and the offer's stock is too low or the price is too high. |
Instance BuyBox information
Only if your market offer is ELIGIBLE to win the BuyBox, then we give more detailed price information (instance_buybox_info) and a suggested price with which you should win the BuyBox.
| Field | Description |
|---|---|
| site_market_competitor_price | The total gross price of the competitor who won the BuyBox for that specific offer in site market currency and including shipping costs. |
| site_market_suggested_offer_price | The suggested gross price (excl. shipping costs that might have been converted) for this offer that would make it get the BuyBox, in site market currency. |
| site_market_suggested_offer_price_diff | Absolute difference between the current offer price (MIN(price, min price)) and the suggested offer price, in site market currency. |
| suggested_offer_price | Same as site_market_suggested_offer_price but in offer price currency. |
| suggested_offer_price_diff | Same as site_market_suggested_offer_price_diff but in offer price currency. |
⚠️If you want to automatically underbid your competitors, set the offers minimum price (reference_min_price) and do not try to keep up by constantly pushing offer price updates yourself.
💡Learn more: Minimum Price Feature - How does it work and what are the main benefits?
Be aware that if a competitor sets or has set a min price that is lower than your current offer price, the competitor's price may also be adjusted on your adjustment. So it might be necessary to iterate and re-adjust the minimum price multiple times to win the BuyBox.