⚠️ This section of the documentation is still work in progress and will improve as our services ripe

General

A buyback order happens if a customer agrees to the winning bid (suggested by the supplybox) for his entered device data that he wants to sell on refurbed. The buyback order flow is more complex than a regular order flow because there is potentially more interaction between you and the customer. This means working with correct order/order_item states is very important. Every Order has an array that holds information about the ordered items. We refer to them as order_items. For now an order is guaranteed to contain only one item (i.e., one device), but this may change in the future (we will inform you in advance)

The general buyback order workflow looks like this:

1. A refurbed customer enters their device’s data on our website.
2. We check if there are any bids for the device and show the price of the supplybox winner to the customer.
3. If the customer decides to sell the device for the price → an order is created. You need to do regular polling for new incoming buyback orders.
4. New orders (”ORDERED” state) must be updated with a shipping label that we will then provide to the customer. The customer sends the device to you and you have the chance to inspect and validate the correctness of the customer's device data.
5. If you are satisfied you can accept the order and trigger the payout. Payouts are always handled by refurbed. If however the device is in worse condition or the device is a different model/has different attributes, you can either reject the order or make another offer to the customer.
6. On rejection, you need to send the device back to the customer and provide the return shipping information.
7. To make a second offer, you need to request the price for the received device (different grading, different model or attributes). We will look at your own bids and return the market bid information at the time the order was created (to avoid potentially unfair price fluctuations that might have happened in the meanwhile).
8. If the customer accepts your second offer the payout is triggered and you can keep the device. Payouts are always handled by refurbed. If the customer rejects your second offer you need to return the device to the customer.

All services and operations concerning the offers must be called with the correct Service in the URL followed by the command/operation.

E.g.: https://api.refurbed.com/refb.merchant.v1.BuybackOrderService/ListBuybackOrders

or

https://api.refurbed.com/refb.merchant.v1.BuybackOrderItemService/MakeSecondOffer

or

https://api.refurbed.com/refb.merchant.v1.BuybackBidService/GetSecondOfferBuybackBidPrice

All calls must be done using POST method.

Read (ListBuybackOrders)

📃 Order information

The endpoint returns a paginated list of all your buyback orders, with the ability to filter and sort orders. The list includes Order ID, Order meta (e.g. date created), Order item state, Customer data, Order Item's details, like product name, attributes, grade, price.

Buyback Order Polling

You can set up a worker to get new buyback orders periodically with the endpoint ListBuybackOrders. All new buyback orders arrive in the state ORDERED. We provide a lot of filters and options to craft responses to your needs: Filters, Sorting, Pagination & Versioning.

Update (UploadShippingLabel / Accept / ConfirmReceived / Reject / NotifyReturned)

🗂️ States

Order states are a concept to organize your buyback orders, keep track of them and trigger communication to the customer. Since orders may contain multiple items in the future, states are managed on order item level. Some states will be set automatically, but some must be set by you. You need to follow the allowed state transitions, you cannot skip states. The routes are designed to indicate the action.

⚠️ Please test the correct flow of states thoroughly when building your integration.

Buyback Order item states & Transitions

📦 Shipping & Return

Shipping Label

Once an order is in “ORDERED” state, you can issue a shipping label and upload it by providing bytes of a PDF file for that specific order item by calling UploadShippingLabel. Refer to the order item id. The order_item’s state will automatically change to “LABEL_SENT” and the customer will receive an email with a link to download the shipping label. The customer should then send their device to you. NOT IMPLEMENTED: If the customer does not send their device or the device is lost in shipping the order will be cancelled automatically after a threshold time (state will change to “CANCELLED”). If you received the device you need to set the state to “RECEIVED” by calling the ConfirmReceived endpoint with the order item id.

Return

If you or the customer rejects an order you need to return the device to the customer. To indicate that you returned the device please call NotifyReturned and set the parcel_tracking_number and parcel_tracking_url of the return shipment. The state of the order item will change from “REJECTED” to “RETURNED” and we will provide the tracking data to the customer.

Second Offer (GetSecondOfferBuybackMarktBid / MakeSecondOffer)

If a received device does not match the entered customer data/your bid, e.g. customer stated a higher grade or storage is different but you still would like to keep the device, you have the option to make a second offer to the customer. By calling GetSecondOfferBuybackMarketBid and specifying the matching grade or device (by referring to product id) and/or attributes in the request body, we will look up the bid price for the device at the time of the order (to keep it fair for the customer).

If you don’t have any bid for the specific device, attribute, and grade combination that would be needed to make the second offer, it is not possible to proceed. In order to avoid sending back a device that you would like to keep, you could create bids for all devices, attributes, and grades and keep the stock at a quantity of 0 for those devices that you don’t want to purchase actively. This will allow you to change the stock before calling GetSecondOfferBuybackMarketBid in order to make the second offer.

You will get a new market_bid in the response, with a new price. If you’re ok with the price you need to call MakeSecondOffer, refer to the order item id and set the new market_bid_id in the field buyback_bid_price_id.
The order item must be in the state “RECEIVED” and will automatically transition to state “SECOND_OFFER”. The customer will get a notification with the new price and can either accept or reject it. If accepted this will automatically trigger the payout mechanic and you can keep the device. Payouts are always handled by refurbed. If rejected you will need to return the device to the customer and call NotifyReturned. Please poll the order states regularly by calling ListBuybackOrders to trigger the follow-up actions in a timely manner.

Testing the BuyBack order flow

ℹ️ To successfully create a new BuyBack order you can click on "Verkaufen" in the left upper corner or you can place a regular order of a refurbished iPhone and follow the below steps.

A new BuyBack order can be created like this:

1. Log in to the public stage of your sandbox as a customer.
   ⚠️ There is a limit of 10 open BuyBack orders per customer. So if you do not completely go through the whole order flow in your testing and simulate the complete fullfillment of the order, you might need to switch to another user or order as unregistered user (w/o account) after 10 placed orders.
2. Open any iPhone product page.
3. Click on Brauchst du dein altes iPhone noch? link in the right section below price.
4. You should see a pop-up to trade in an old device.
5. Choose a device, where you have the winning bid in the SupplyBox. You can find them in the SupplyBox section of the merchant interface of your sandbox.
   The SupplyBox state of the bid has to be in state WON.
6. Continue the process by filling in the device details matching this winning bid and provide the bank details at the end (any valid IBAN. Find examples here: https://ibanvalidieren.de/beispiele.html)

7. The to-be-sold device should now appear where the Brauchst du dein altes iPhone noch? link was:

   

8. You can now proceed with the regular order to finish the BuyBack order.
9. Add the iPhone, where you initially started (step 2) to the cart.
10. Proceed with checkout (pick a test card from here: https://stripe.com/docs/testing#cards)
11. After successful checkout, the buyback order should have been created and be visible in the merchant interface of your sandbox (and also collectible via API of course)

Please note that:

• No emails will be sent to the customer email address you use when creating the orders.
• Therefore, second offers (accept/reject) from the customer's perspective cannot be tested.