Skip to main content
GET
/
returns
Retrieve a list of returns
curl --request GET \
  --url https://panel.sendcloud.sc/api/v3/returns \
  --header 'Authorization: Basic <encoded-value>'
{
  "next": "http://panel.sendcloud.sc/api/v3/returns?cursor=cD0z&page_size=1",
  "previous": "http://panel.sendcloud.sc/api/v3/returns?cursor=cD0z&page_size=2",
  "data": [
    {
      "created_at": "2022-07-18T15:34:21.869312+02:00",
      "is_cancellable": false,
      "label_cost": {
        "value": 6.15,
        "currency": "EUR"
      },
      "delivered_at": 1734946171662,
      "delivered_at_iso": "2022-07-18T15:34:21.869312+02:00",
      "shipping_product": {
        "code": "postnl:standard/return"
      },
      "collo_count": 1,
      "brand_id": 1,
      "tracking_number": "JVGL1234567800001339",
      "dimensions": {
        "length": 3,
        "width": 3,
        "height": 3,
        "unit": "cm"
      },
      "parcel_items": [],
      "insurance": false,
      "label_url": "https://panel.sendcloud.sc/api/v2/labels/label_printer/7",
      "label": {
        "label_printer": "https://panel.sendcloud.sc/api/v2/labels/label_printer/7",
        "normal_printer": [
          "https://panel.sendcloud.sc/api/v2/labels/normal_printer/7?start_from=0",
          "https://panel.sendcloud.sc/api/v2/labels/normal_printer/7?start_from=1",
          "https://panel.sendcloud.sc/api/v2/labels/normal_printer/7?start_from=2",
          "https://panel.sendcloud.sc/api/v2/labels/normal_printer/7?start_from=3"
        ]
      },
      "tracking_url": "https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=postnl&code=JVGL1234567800001339&destination=NL&lang=en-us&source=NL&type=parcel&verification=5611+JV&servicepoint_verification=&created_at=2022-07-18",
      "send_tracking_emails": false,
      "weight": {
        "value": 1,
        "unit": "kg"
      },
      "from_address": {
        "name": "Gregory van der Poel",
        "address_line_1": "Merchant Street",
        "address_line_2": "",
        "house_number": "1",
        "postal_code": "5611 LX",
        "city": "Eindhoven",
        "country_code": "NL",
        "email": "merchant@email.com"
      },
      "to_address": {
        "name": "Customer3",
        "po_box": "",
        "address_line_1": "Customer Street3",
        "address_line_2": "",
        "house_number": "12",
        "postal_code": "5611 JV",
        "city": "Eindhoven",
        "state_province_code": "Noord Brabant",
        "country_code": "NL",
        "email": "customer@email.com"
      },
      "reason": {
        "id": 1,
        "description": "Product did not match expectations"
      },
      "refund": {
        "refund_type": "exchange",
        "message": "Exchange for size M"
      },
      "return_fee": {
        "value": 1.5,
        "currency": "EUR"
      },
      "order_number": "",
      "status_history": [
        {
          "carrier_update_timestamp": "2022-07-18T15:34:21.862840+02:00",
          "parcel_status_history_id": "1",
          "parent_status": "Ready to Ship",
          "carrier_code": "some-carrier-code",
          "carrier_message": "some-carrier-message"
        }
      ],
      "customs_invoice_nr": "",
      "customs_shipment_type": 2
    }
  ]
}
The response includes return data for each parcel, plus up-to-date tracking history. The returned data is paginated and has a default number of items per page of 40, which can be controlled by the page_size query param. You can filter the results to only include return parcels created within a specific time frame using the from_date and to_date parameters, or based on the parent_parcel_status.

Authorizations

​
Authorization
string
header
required

Basic Authentication using API key and secrets is currently the main authentication mechanism.

Query Parameters

​
cursor
string

The cursor query string is used as the pivot value to filter results. If no value is provided, the first page of results will be returned. To get this value, you must encode the offset, reverse and position into a base64 string.

There are 3 possible parameters to encode:

  • o: Offset
  • r: Reverse
  • p: Position

For example, r=1&p=300 encoded as a base64 string would be cj0xJnA9MzAw. The query string would then be cursor=cj0xJnA9MzAw.

Example:

"cj0xJnA9MzAw"

​
from_date
string
required

Excludes all returns before this datetime

Example:

"2022-04-06 00:00:00"

​
to_date
string
required

Excludes all returns after this datetime

Example:

"2022-04-07 00:00:00"

​
parent_parcel_status
enum<string>

Search for returns with this parent status

Available options:
ready-to-send,
announced,
to-sorting,
delayed,
sorted,
unsorted,
sorting,
delivery-failed,
delivery-forced,
delivered,
awaiting-customer-pickup,
announced-uncollected,
collect-error,
unsorted2,
undeliverable,
shipment-on-route,
driver-on-route,
picked-up-by-driver,
collected-by-customer,
no-label,
announcing,
cancelling-upstream,
cancelling,
cancelled,
cancelled-upstream,
unknown,
announcement-failed,
at-customs,
at-sorting-centre,
refused-by-recipient,
returned-to-sender,
delivery-method-changed,
delivery-date-changed,
delivery-address-changed,
exception,
address-invalid
Example:

"announced"

​
page_size
number

Refers to the number of items per page

Required range: 1 <= x <= 40
Example:

10

Response

200 - application/json

OK

​
next
string

A cursor-based pagination url to go forward

​
previous
string

A cursor-based pagination url to go backwards

​
data
Return Object · object[]