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"
      },
      "shipping_option": {
        "code": "postnl:standard/signature"
      },
      "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/v3/parcels/7/documents/label",
      "label": {
        "label_printer": "https://panel.sendcloud.sc/api/v3/parcels/7/documents/label",
        "normal_printer": [
          "https://panel.sendcloud.sc/api/v3/parcels/7/documents/label?paper_size=a4",
          "https://panel.sendcloud.sc/api/v3/parcels/7/documents/label?paper_size=a4",
          "https://panel.sendcloud.sc/api/v3/parcels/7/documents/label?paper_size=a4",
          "https://panel.sendcloud.sc/api/v3/parcels/7/documents/label?paper_size=a4"
        ]
      },
      "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
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://sendcloud.dev/llms.txt

Use this file to discover all available pages before exploring further.

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[]