Partner API - Buyers

💡 Note: This is our standard partner flow. Some parties (like Tradein.nl) have their own API which we connect to as a client - that flow works in reverse and is outside the scope of this documentation.
✅ Prices via our API✅ Orders via your webhook✅ Label back via our API

Full integration flow

🔍

You fetch the catalog

← You → Us

Search devices to learn model_ids and condition questions

💰

You push your buy prices

← You → Us

Per model_id you specify your offer - our system uses this to determine the best buyer

🛒

Customer places an order on refurbished.trade

Refurbished.trade internal

Customer fills in conditions, our system selects the winning buyer based on submitted prices

📬

We push the order to you

Us → You

We send a POST to your webhook URL with all customer and order data

🏷️

You push the shipping label back

← You → Us

Process the order, generate a label, and return the PDF URL via our API

Authentication

Our API endpoint

POSThttps://refurbished.trade/api/functions/partnerAPI

Auth header

Authorization: Bearer <username>:<api_key>

Credentials are provided during the onboarding process.

1

Fetch the catalog

Use action: "search" to look up devices and discover their model_ids. You'll need those model_ids to submit prices.

Request

HTTP
POST https://refurbished.trade/api/functions/partnerAPI
Authorization: Bearer <username>:<api_key>
Content-Type: application/json

{
  "action": "search",
  "query": "iPhone 15 Pro",
  "limit": 10
}

Response

JSON
{
  "devices": [
    {
      "model_id": "apple-iphone-15-pro-128gb",
      "title": "Apple iPhone 15 Pro 128GB",
      "brand": "Apple",
      "image_url": "https://...",
      "questions": [
        {
          "id": "q1",
          "title": "Screen condition?",
          "answers": [
            { "id": "a1", "label": "Perfect - no scratches" },
            { "id": "a2", "label": "Minor scratches (normal use)" },
            { "id": "a3", "label": "Cracked or damaged" }
          ]
        }
      ]
    }
  ],
  "total": 1
}
2

Submit buy prices

Send your buy price per model_id. Our system compares all partners and routes each order to whoever has the highest offer. You can update prices as often as you like - changes take effect immediately.

💡 Condition-specific pricing: You can optionally include condition_answers (same format as returned by search) to push a price for a specific condition. A price without condition_answers acts as the base price for that model; condition-specific entries override it for matching orders.

Request

HTTP
POST https://refurbished.trade/api/functions/partnerAPI
Authorization: Bearer <username>:<api_key>
Content-Type: application/json

{
  "action": "push-prices",
  "prices": [
    {
      "model_id": "apple-iphone-15-pro-128gb",
      "buy_price": 390,
      "currency": "EUR"
    },
    {
      "model_id": "apple-iphone-15-pro-128gb",
      "buy_price": 310,
      "currency": "EUR",
      "condition_answers": [
        { "question_id": "q1", "answer_id": "a3" }
      ]
    },
    {
      "model_id": "samsung-galaxy-s24-128gb",
      "buy_price": 210,
      "currency": "EUR"
    }
  ]
}

Response

JSON
{
  "success": true,
  "updated": 3,
  "message": "3 price(s) updated."
}
3

Webhook - receive orders

Implement a POST endpoint on your server. Whenever you are the winning buyer, we push the full order data to your webhook. Share your webhook URL via service@refurbished.store.

Always return HTTP 200, even if you're still processing the order internally. Any other status code will trigger a retry.

Payload we send to you

HTTP
POST https://your-system.com/webhook/refurbished-trade
Content-Type: application/json
X-Refurbished-Signature: <hmac-signature>

{
  "event": "order.created",
  "order_id": "abc123...",
  "order_number": "RT-2026-ABCDE123",
  "device_title": "Apple iPhone 15 Pro 128GB",
  "device_model_id": "apple-iphone-15-pro-128gb",
  "offer_price": 390,
  "currency": "EUR",
  "condition_answers": [
    { "question_id": "q1", "answer_id": "a2" }
  ],
  "customer": {
    "name": "Jan de Vries",
    "email": "jan@example.com",
    "phone": "+31612345678",
    "address": "Hoofdstraat 12",
    "postal_code": "3769AV",
    "city": "Soesterberg",
    "country": "NL"
  },
  "created_at": "2026-04-09T10:30:00Z"
}

Example handler (Node.js)

JavaScript
// Express.js example
app.post('/webhook/refurbished-trade', express.json(), (req, res) => {
  const { event, order_id, order_number, customer, device_title, offer_price } = req.body;

  if (event === 'order.created') {
    // Store order in your system and trigger internal workflow
    console.log(`New order ${order_number}: ${device_title} - €${offer_price}`);
    console.log(`Customer: ${customer.name} <${customer.email}>`);

    // Required: always return HTTP 200 so we know you received it
    return res.json({ received: true });
  }

  res.status(400).json({ error: 'Unknown event' });
});
4

Return the shipping label

Once you've generated a shipping label, send the PDF URL to our label endpoint. We handle the rest automatically: the order status is updated to label_printed and the customer receives an email with the label.

Label endpoint

https://refurbished.trade/api/functions/pushLabelFromBuyer

Request

HTTP
POST https://refurbished.trade/api/functions/pushLabelFromBuyer
Authorization: Bearer <username>:<api_key>
Content-Type: application/json

{
  "order_id": "abc123...",
  "label_url": "https://your-system.com/labels/label-abc123.pdf",
  "tracking_number": "3SABCDEF123456789NL"
}

Response

JSON
{
  "success": true,
  "order_id": "abc123...",
  "label_status": "success",
  "message": "Label received. Customer has been notified."
}

Order statuses

registeredlabel_printedshippedin_transitdeliveredpaid

After returning the label we automatically set the order to label_printed and email the customer with the label - you don't need to do anything else.

Get started

Send your webhook URL and a test request to service@refurbished.store.
We'll configure your account and generate your API credentials.