Stock API

Version 1 · Make an API key

Keep your stock on Refurbr Network up to date from your own system, line by line. Refurbr customers can also create batches: build a batch in Refurbr, post it to the network, and let the stock follow automatically.

• Base URL: https://network.refurbr.co.uk/api/v1/stock
• Sign in: Authorization: Bearer rn_…, an API key
• Format: JSON. Send Accept: application/json and, with a body, Content-Type: application/json
• Limit: 120 requests a minute per key
• Version: v1. New fields may be added to responses; existing ones won't change meaning

Quick start#

1. Make a key. In Refurbr Network, open Account → API keys and choose New key. Only the primary account holder can make keys. Name it after the system that will use it, and copy it straight away: it's only shown once.

2. Check it works.

   curl https://network.refurbr.co.uk/api/v1/stock/me \
     -H "Authorization: Bearer rn_…" -H "Accept: application/json"
   

   {
     "business": { "id": 11, "name": "Your Business Ltd", "currency": "GBP" },
     "key": { "name": "Warehouse system", "prefix": "rn_gSHNzeL" },
     "can_create_batches": false,
     "max_lines": 2000
   }
   

3. Give your lines SKUs. The API finds lines by SKU. Add them to your batches' stock lines on the website, or import a CSV with a sku column. A batch described in text can be turned into lines from its edit page ("Turn into lines").

4. Send your stock. For example, set one line to 32 available:

   curl -X PATCH https://network.refurbr.co.uk/api/v1/stock/batches/42/stock \
     -H "Authorization: Bearer rn_…" -H "Accept: application/json" -H "Content-Type: application/json" \
     -d '{"lines": [{"sku": "IP13-128-BLU-A", "available": 32}]}'
   

How stock works#

A batch's stock is a list of lines: an item, a grade, a price per unit (when the batch is priced per unit) and a SKU, your own reference. The batch's units, grade and "from" price come from its lines.

• Send what's available now. Refurbr Network keeps what each line has sold, so a line lists units_sold + available. Sales made on the network take units off the right lines straight away.
• Lines are matched by SKU, ignoring case. Lines without a SKU can only be changed on the website.
• Promised stock is protected. When a buyer and seller agree an order summary, its units are promised on the lines it's for. You can't set a line below what's promised on it, or the batch below what's sold and promised (units_sold + units_promised).
• Running out marks the batch sold and takes it off the network; stock added back puts it on again.

An update is refused, and nothing changes, when:

• it would cut a line below what's promised on it, or leave the batch with no stock at all when nothing has sold (hide the batch on the website instead);
• the batch is at auction (scheduled or live);
• it changes a price while an order summary is active on the batch (stock can still change, as long as it covers the order);
• a SKU new to the batch comes without a description, grade or (priced per unit) price.

Keeping in sync#

The simplest reliable approach is to send each batch's whole stock with PUT whenever it changes, or on a schedule (every few minutes is plenty). PUT is safe to repeat: sending the same stock twice changes nothing. Use PATCH when you only know about one or two lines. Keep the batch's Refurbr Network id (or give it your own reference when you create it) so you can find it again.

Objects#

Batch#

{
  "id": 42,
  "reference": "RB-5531",
  "refurbr_batch_id": "B-5531",
  "title": "Mixed iPhone 13 range, graded",
  "status": "live",
  "on_network": true,
  "url": "https://network.refurbr.co.uk/portal/batches/42",
  "currency": "GBP",
  "price_mode": "unit",
  "grade": "A-C",
  "units": 118,
  "units_sold": 12,
  "units_available": 106,
  "units_promised": 6,
  "lines": [
    { "id": 7, "sku": "IP13-128-BLU-A", "description": "iPhone 13 128GB Blue", "grade": "A",
      "units": 40, "units_sold": 8, "available": 32, "price": "245.00" }
  ],
  "updated_at": "2026-10-15T21:40:00+00:00"
}

Endpoints#

GET /me#

Who the key belongs to: business (id, name, currency), key (name, prefix), can_create_batches and max_lines.

GET /batches#

Your batches, newest first, 50 to a page. Filter with ?reference=RB-5531 or ?status=live (live, under_offer, sold), and page with ?page=2.

{ "data": [ { "id": 42, "…": "…" } ], "links": { "next": "…" }, "meta": { "current_page": 1, "last_page": 1, "total": 8 } }

GET /batches/{id}#

One of your batches. Another business's batch is 404.

PATCH /batches/{id}/stock#

Set the stock of the lines you send; the others stay as they are.

{ "lines": [
  { "sku": "IP13-128-BLU-A", "available": 32 },
  { "sku": "IP13-128-GRN-B", "available": 6, "description": "iPhone 13 128GB Green", "grade": "B", "price": "209.00" }
] }

A new SKU with available: 0 is ignored. Returns the Batch.

PUT /batches/{id}/stock#

The whole stock. Same body, but lines with a SKU you leave out go to 0: removed if they've never sold, kept at what they sold if they have. Returns the Batch.

POST /batches#

Create a batch with its stock. Only for businesses linked to a Refurbr account (403 otherwise); everyone else creates batches on the website and keeps them up to date here.

{
  "category_id": 3,
  "title": "Dell Latitude 7420 mix",
  "description": "Optional notes: condition, what's included.",
  "price_mode": "unit",
  "reference": "RB-5531",
  "refurbr_batch_id": "B-5531",
  "lines": [
    { "sku": "L7420-I5", "description": "Latitude 7420 i5 16GB", "grade": "A", "available": 30, "price": "289.00" },
    { "sku": "L7420-I7", "description": "Latitude 7420 i7 16GB", "grade": "B", "available": 12, "price": "319.00" }
  ]
}

Returns 201 with the Batch. It's live straight away, and reaches the network once your business is verified.

Errors#

A 422 says what to fix, keyed by field (lines.0.available is the first line's available):

{
  "message": "SKU IP13-128-BLU-A has 6 promised in order summaries, so it can't go below that. Nothing was changed.",
  "errors": {
    "lines.0.available": ["SKU IP13-128-BLU-A has 6 promised in order summaries, so it can't go below that. Nothing was changed."]
  }
}

Every response includes X-RateLimit-Limit and X-RateLimit-Remaining.

Keys and security#

• Treat a key like a password: keep it in your system's settings or a secrets manager, never in code you share or in a browser.
• Make one key per system, so you can revoke one without stopping the others. Revoking takes effect straight away.
• A key acts with the rights of whoever made it, or the primary account holder if they've left. Its last use is shown in Account → API keys, and stock changes appear in your business's history.

Without a system of your own#

On a batch's edit page, Import CSV reads a spreadsheet of lines (item, grade, units, and optionally price and SKU) into the batch. Download the template from the import window.