Biklo for developersTESTsandbox-api.biklo.comchange

List returns

GET/v1/returns

scope orders.read

Returns buyers have raised against your orders.

Query parameters#

NameExample
limit50Max 100
cursor—next_cursor

Response#

FieldTypeDescription
countintegerHow many returns in this page.
next_cursorstring|nullPass back as ?cursor=; null on the last page.
dataarrayReturns buyers have requested on your orders.
data[].idintegerThe return id. To accept or reject, use order_id: POST /v1/returns/{order_id}/accept|reject.
data[].order_idintegerWhich order it is against.
data[].reasonstring|nullWhat the buyer wrote.
data[].order_statusstringThe ORDER's status, not the return's — same vocabulary as GET /v1/orders/{id}.
data[].requested_atstringISO-8601 UTC, when the buyer asked.
data[].return_order_idinteger|nullThe return parcel's own order (buyer → you); its tracking is the parcel coming back. null until the buyer has sent it.
data[].referencestring|nullYour reference of the original order.
data[].inspectionobject|nullYour inspection of the returned product. null until the parcel is back with you (and on orders paid before Biklo Payments). Until a decision the money for the returned lines stays held — nothing is refunded or paid out on a timer.
data[].inspection.statusstringawaiting_seller: accept or reject before deadline_at. disputed: you rejected it, the Biklo team decides. awaiting_admin: the deadline passed, the Biklo team decides. accepted: the buyer was refunded in full. partially_refunded: part refunded, the rest released to you. rejected: no refund, the money released to you.

Accepts awaiting_seller · disputed · awaiting_admin · accepted · partially_refunded · rejected

data[].inspection.delivered_atstringISO-8601 UTC, when the return parcel was delivered to you.
data[].inspection.deadline_atstringISO-8601 UTC. Accept or reject before this (48 h after delivery by default).
data[].inspection.refundobjectWhat the buyer gets back if you accept: the price of the returned lines.
data[].inspection.refundedobject|nullWhat the buyer actually got back, once decided (amount 0 = no refund). null while open.
data[].inspection.decided_atstring|nullISO-8601 UTC, when it was decided.
data[].inspection.decided_bystring|nullseller (you) or admin (the Biklo team).

Accepts seller · admin

data[].inspection.can_acceptbooleanWhether POST /v1/returns/{order_id}/accept would work now.
data[].inspection.can_rejectbooleanWhether POST /v1/returns/{order_id}/reject would work now.
data[].inspection.refund.amountintegerMinor units.
data[].inspection.refund.currencystringISO 4217.
data[].itemsarrayThe order's lines being returned.
data[].items[].idintegerThe order line id (as in GET /v1/orders/{id}).
data[].items[].product_idintegerThe product.
data[].items[].quantityintegerPieces on the line.
data[].items[].total_priceobjectThe line's price.
data[].items[].total_price.amountintegerMinor units.
data[].items[].total_price.currencystringISO 4217.
data[].items[].return_statusstringrequested = on its way back or being inspected, money held; returned = the buyer was refunded; rejected = not refunded, the money went to you.

Accepts requested · returned · rejected

Example

{
    "count": 1,
    "next_cursor": null,
    "data": [
        {
            "id": 8,
            "order_id": 711,
            "return_order_id": 742,
            "reference": "SBXORD-SJP6NHXY",
            "reason": "Wrong size delivered",
            "order_status": "delivered",
            "requested_at": "2026-09-09T19:45:00Z",
            "inspection": {
                "status": "awaiting_seller",
                "delivered_at": "2026-09-12T09:10:00Z",
                "deadline_at": "2026-09-14T09:10:00Z",
                "refund": {
                    "amount": 179900,
                    "currency": "RON"
                },
                "refunded": null,
                "decided_at": null,
                "decided_by": null,
                "can_accept": true,
                "can_reject": true
            },
            "items": [
                {
                    "id": 1123,
                    "product_id": 237224,
                    "quantity": 1,
                    "total_price": {
                        "amount": 179900,
                        "currency": "RON"
                    },
                    "return_status": "requested"
                }
            ]
        }
    ]
}

Failures use the shared error envelope — a machine-readable code and a request_id to quote to support. Error handling.

curl -X GET "https://sandbox-api.biklo.com/v1/returns?limit=50" \
  -H "Authorization: Bearer bk_test_YOUR_KEY"
<?php

$ch = curl_init('https://sandbox-api.biklo.com/v1/returns?limit=50');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'GET',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer bk_test_YOUR_KEY',
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "bk_test_YOUR_KEY");

var request = new HttpRequestMessage(
    new HttpMethod("GET"),
    "https://sandbox-api.biklo.com/v1/returns?limit=50");

var response = await client.SendAsync(request);
var json = await response.Content.ReadAsStringAsync();

import requests

response = requests.get(
    "https://sandbox-api.biklo.com/v1/returns?limit=50",
    headers={"Authorization": "Bearer bk_test_YOUR_KEY"},
)

data = response.json()

const response = await fetch("https://sandbox-api.biklo.com/v1/returns?limit=50", {
  method: "GET",
  headers: {
    Authorization: "Bearer bk_test_YOUR_KEY"
  }
});

const data = await response.json();

import java.net.http.*;
import java.net.URI;

var client = HttpClient.newHttpClient();

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://sandbox-api.biklo.com/v1/returns?limit=50"))
    .header("Authorization", "Bearer bk_test_YOUR_KEY")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());