⚠️ This section of the documentation is still work in progress and will improve as our services ripe
A bid is an offer for products where you have demand and that you are willing to buy back from customers or other sellers. Bids are based on refurbed products and respectively use the refurbed’s product_id. Products are a parent level of refurbed instances (the variants of a product). If you browse refurbed e.g. https://www.refurbed.ie/c/smartphones/, the names you see are the product names e.g. iPhone SE (2020).
All services and operations concerning the offers must be called with BuybackBidService in the URL followed by the command/operation.
E.g.:
https://api.refurbed.com/refb.merchant.v1.BuybackBidService/ListBuybackBids
or
https://api.refurbed.com/refb.merchant.v1.BuybackProductService/ListBuybackProducts
All calls must be done using POST method.
Read (ListBuybackBids / ListBuybackProducts)
List Buyback Bids
You can get an overview of all your existing bids by calling the ListBuybackBids endpoint. The response will contain an array/list of all bids according to the pagination rules with all related information. As for every read command that is served over our API you can use extensive filters and sorting by sending a specific payload in the request header.
List Buyback Products
To list all Buyback products call BuybackProductService/ListBuybackProducts. This endpoint will return you the product_id which is needed to create your bids. You can apply filters and pagination to find specific products or product groups.
ℹ️ Currently, not all products that are available in our product catalog can be used for Buyback. We will gradually increase the selection.
Create (CreateBuybackBid / CreateBuybackMarketBid)
Bids can only be created on products that are already existing in the refurbed product catalog and are enabled by us for Buyback. The reference will be the product_id not to be confused with the instance_id which is used for regular offers if you sell goods on the refurbed marketplace. To retrieve the product_id please check “List Buyback products” above.
To specify the product criteria further, additional attributes must be provided. Attributes are key-value pairs e.g.: Storage: 64GB. Attribute keys can be found on any refurbed product page e.g.: https://www.refurbed.ie/p/iphone-se-2020/ in the specification table. All attribute_ids of attribute keys are currently exposed here https://api.refurbed.io/v1/attributes/ (GET). This endpoint will be deprecated and eventually replaced by a new one in the realms of our new API (api.refurbed.com).
Currently, the only attribute that we allow is Storage with id: 2.
A bid must also contain a grade and price. With the stock value, you can define how many items you are willing to buy. Stock can also be specified but is not mandatory on creation. Leaving the stock setting our or setting it to null will signal that you are willing to buy an unlimited amount of devices. Bid prices are set for specific markets (”MarketBids”), but can also be set to 0 (zero) and treated as placeholders where the price is updated later.
The customer sees the price that already has the refurbed commission deducted.
Example: you create a bid with price 100 EUR for a phone model, we automatically deduct 10% as commission and show to the customer 90 EUR; the customer gets 90 EUR, refurbed 10 EUR - in total the seller has to pay 100 EUR (the initially set bid price).
To create a new bid you need to call CreateBuybackBid with at least one attribute and at least one market_bid. A bid, meaning the combination of product_id, attributes, and grade, is unique and therefore can only exist once. Attribute values are validated by us so that you cannot create a bid for a product with attributes that are not valid, e.g. an iPhone 13 with 127 GB storage, or whose product configuration is nonexistent in refurbed e.g. an iPhone 13 with (only) 64 GB.
If you want to add an additional market price for a bid you need to call CreateBuybackMarketBid and refer to the bid_id. The request body also needs to hold market_code, currency_code, and price. Every market-specific bid price will get its own id, the market_price_id.
It is also possible to add an SKU (or a similar identifier from your system) that can be used to refer to your bid. E.g. to update market-specific bid prices you can refer to the SKU in combination with the market_code.
ℹ️ SKUs are optional but if used, must be unique and max. 256 chars long!
What happens to created bids is described here: Buyback Supplybox.
Update (UpdateBuybackBid / UpdateBuybackMarketBid)
Prices
If you only want to update a bid price for a specific market you need to call UpdateBuybackMarketBid and refer to the market_price_id or the bid’s SKU in combination with the market_code. You also always need to provide the currency in the request body. If you set the bid price to 0 (zero) and your bid is the only one in the supplybox in that configuration, the customer will be referred to an offer to recycle their device
Stock
With the stock value, you can define how many items you are willing to buy. To update a bid's stock, call UpdateBuybackBid referring to the bid’s id or the bids SKU. Setting it to null will signal that you are willing to buy an unlimited amount of devices.
Delete (DeleteBuybackBid / DeleteBuybackMarketBid)
To delete a bid completely, call DeleteBuybackBid and refer to the bid id or the bid’s SKU in the request body. If you only want to delete a specific regional bid price you need to call DeleteBuybackMarketBid and refer to the market_price_id (not the bid’s id) in the request body. You cannot delete all Market Bids. At least one Market Bid must exist.