Skip to main content
GET
/
returns
/
{id}
Retrieve a return
curl --request GET \
  --url https://panel.sendcloud.sc/api/v3/returns/{id} \
  --header 'Authorization: Basic <encoded-value>'
{
  "from_address": {
    "name": "John Doe",
    "address_line_1": "Stadhuisplein",
    "postal_code": "1013 AB",
    "city": "Eindhoven",
    "country_code": "NL",
    "company_name": "Sendcloud",
    "house_number": "50",
    "address_line_2": "Apartment 17B",
    "po_box": "<string>",
    "state_province_code": "IT-RM",
    "email": "johndoe@gmail.com",
    "phone_number": "+319881729999"
  },
  "to_address": {
    "name": "John Doe",
    "address_line_1": "Stadhuisplein",
    "postal_code": "1013 AB",
    "city": "Eindhoven",
    "country_code": "NL",
    "company_name": "Sendcloud",
    "house_number": "50",
    "address_line_2": "Apartment 17B",
    "po_box": "<string>",
    "state_province_code": "IT-RM",
    "email": "johndoe@gmail.com",
    "phone_number": "+319881729999"
  },
  "shipping_product": {
    "code": "<string>"
  },
  "weight": {
    "value": 14.5,
    "unit": "g"
  },
  "send_tracking_emails": false,
  "is_cancellable": true,
  "status_history": [
    {
      "carrier_update_timestamp": "2023-11-07T05:31:56Z",
      "parcel_status_history_id": "<string>",
      "parent_status": "<string>",
      "carrier_code": "<string>",
      "carrier_message": "<string>"
    }
  ],
  "created_at": "2022-08-09T14:32:21.463473+02:00",
  "dimensions": {
    "length": 15,
    "width": 20.5,
    "height": 37,
    "unit": "mm"
  },
  "collo_count": 1,
  "parcel_items": [
    {
      "item_id": "5552",
      "description": "T-Shirt XL",
      "quantity": 1,
      "weight": {
        "value": 14.5,
        "unit": "g"
      },
      "price": {
        "value": 123,
        "currency": "EUR"
      },
      "value": {
        "value": 123,
        "currency": "EUR"
      },
      "hs_code": "6205.20",
      "origin_country": "NL",
      "sku": "TS1234",
      "product_id": "19284",
      "return_reason_id": "1",
      "return_message": "Too big",
      "mid_code": "NLOZR92MEL",
      "material_content": "100% Cotton",
      "intended_use": "Personal use",
      "properties": {
        "size": "red",
        "color": "green"
      },
      "variant_id": "size-l",
      "return_reason": {
        "id": 1,
        "description": "Too big for me"
      }
    }
  ],
  "brand_id": 1,
  "label_url": "https://panel.sendcloud.sc/api/v2/labels/label_printer/8",
  "label": {
    "normal_printer": [
      "https://panel.sendcloud.sc/api/v2/labels/normal_printer/8?start_from=0",
      "https://panel.sendcloud.sc/api/v2/labels/normal_printer/8?start_from=1",
      "https://panel.sendcloud.sc/api/v2/labels/normal_printer/8?start_from=2",
      "https://panel.sendcloud.sc/api/v2/labels/normal_printer/8?start_from=3"
    ],
    "label_printer": "https://panel.sendcloud.sc/api/v2/labels/label_printer/8"
  },
  "label_cost": {
    "value": 123,
    "currency": "EUR"
  },
  "insurance": true,
  "tracking_number": "3SSEND12345678",
  "tracking_url": "https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=sendcloud&code=3SSEND12345678&destination=NL&lang=en-gb&source=NL&type=letter&verification=1001+VV&servicepoint_verification=&created_at=2022-07-27",
  "delivered_at": 1734946171662,
  "delivered_at_iso": "2022-08-09T14:32:21.463473+02:00",
  "reason": {
    "id": 1,
    "description": "Too big for me"
  },
  "refund": {
    "refund_type": "exchange",
    "message": "Exchange for size M"
  },
  "return_fee": {
    "value": 123,
    "currency": "EUR"
  },
  "order_number": "ORD12345",
  "contract": 123,
  "customs_invoice_nr": "<string>",
  "customs_shipment_type": 0,
  "delivery_option": "drop_off_point",
  "images": [
    {
      "product_id": "123456",
      "uploaded_image": "https://example.com/image.png",
      "thumbnail_image": "https://example.com/thumbnail.png",
      "description": "My broken camera, with a crack on the lens"
    }
  ],
  "status": "open",
  "customs_information": {
    "invoice_number": "INV-123",
    "export_reason": "commercial_goods",
    "export_type": "private",
    "invoice_date": "2023-08-24",
    "discount_granted": {
      "value": "14.99",
      "currency": "EUR"
    },
    "freight_costs": null,
    "insurance_costs": {
      "value": "3.60",
      "currency": "EUR"
    },
    "other_costs": {
      "value": "1.2",
      "currency": "EUR"
    },
    "general_notes": "Compliance: Goods comply with international safety standards (CE certified).",
    "additional_declaration_statements": [
      "With reference to the above shipment, I understate that the content is not made of leather parts of animal species protected by the Washington Convention.",
      "I solemnly declare that the contents of this document represent a true and accurate account of the events as they occurred. I acknowledge my responsibility for the information presented herein and understand that any misrepresentation or falsification may result in legal consequences or other penalties as applicable."
    ],
    "importer_of_record": {
      "name": "John Doe",
      "company_name": "ImporterCo",
      "address_line_1": "Maple Avenue",
      "house_number": "123",
      "postal_code": "90210",
      "city": "Springfield",
      "country_code": "US",
      "state_province_code": "US-MA",
      "telephone": "+15551234567",
      "email": "info@importer-of-record-example.com"
    },
    "tax_numbers": {
      "sender": [
        {
          "name": "VAT",
          "country_code": "NL",
          "value": "NL123456789B01"
        },
        {
          "name": "EORI",
          "country_code": "NL",
          "value": "NL123456789"
        }
      ],
      "receiver": [
        {
          "name": "EIN",
          "country_code": "US",
          "value": "123456789"
        }
      ],
      "importer_of_record": [
        {
          "name": "EIN",
          "country_code": "US",
          "value": "987654321"
        }
      ]
    },
    "return_data": {
      "return_postal_code": "1111 AA",
      "outbound_tracking_number": "JT1234567890",
      "outbound_shipment_date": "2023-08-14",
      "outbound_carrier_name": "UPS"
    }
  },
  "errors": [
    {
      "id": "<string>",
      "links": {
        "about": "<string>"
      },
      "status": "<string>",
      "code": "unknown_field",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>",
        "parameter": "<string>",
        "header": "<string>"
      },
      "meta": {}
    }
  ]
}
This endpoint allows you to retrieve information about a specific return parcel based on the return id. A return id is assigned to every return you create in Sendcloud, and can be retrieved for all return parcels via the Retrieve a list of returns endpoint. The returned object contains all relevant information about the return parcel, including up-to-date tracking information.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
id
integer
required

The internal Sendcloud id of this return

Example:

1751075

Response

OK

A Sendcloud return object

​
from_address
Address Object · object
required

Sendcloud Address object

​
to_address
Address Object · object
required

Sendcloud Address object

​
shipping_product
Shipping Product Code · object
required

Sendcloud shipping product code

​
weight
Weight · object
required

Weight in the specified unit

​
send_tracking_emails
boolean
default:false
required

When true, Sendcloud will send out the default track and trace emails

​
is_cancellable
boolean
required

Whether the incoming parcel of this return can be cancelled

​
status_history
Detailed Tracking status · object[]
required

List with the timeline of your return status

Minimum array length: 1
​
created_at
string<date-time>
required

Date and time of creation of this return

Example:

"2022-08-09T14:32:21.463473+02:00"

​
dimensions
Dimension · object

Dimension in the specified unit

​
collo_count
integer
default:1

The number of collos this return consists of

Required range: x >= 1
​
parcel_items
Parcel Item Object · object[]

List of items contained in this return. Required outside the EU.

​
brand_id
integer

The ID of the brand this Return belongs to.

Required range: x >= 1
Example:

1

​
label_url
string | null
deprecated

URL to download the label. This can be null because it might not be announced yet. Deprecated in favour of the label field.

Example:

"https://panel.sendcloud.sc/api/v2/labels/label_printer/8"

​
label
object

URLs to download the label, if the parcel has been announced.

​
label_cost
Price Object · object

Price in the specified currency

​
insurance
boolean

Whether the return parcel is insured

​
tracking_number
string | null

This can be null because it might not be announced yet.

Example:

"3SSEND12345678"

​
tracking_url
string | null

URL to track your return. This can be null because it might not be announced yet.

Example:

"https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=sendcloud&code=3SSEND12345678&destination=NL&lang=en-gb&source=NL&type=letter&verification=1001+VV&servicepoint_verification=&created_at=2022-07-27"

​
delivered_at
number | null
deprecated

A unix timestamp indicating the delivery time of this return. Deprecated in favour of the delivered_at_iso field.

Example:

1734946171662

​
delivered_at_iso
string<date-time> | null

Date and time of delivery of this return

Example:

"2022-08-09T14:32:21.463473+02:00"

​
reason
Return reason Object · object

The reason this Return was created. This could be on the item level or the whole Return.

​
refund
Return refund Object · object

Information about the compensation chosen by the customer for the returned items

​
return_fee
Price With Any Currency · object

The fee associated with this return

​
order_number
string

Order number filled by the user

Example:

"ORD12345"

​
contract
integer

ID of the contract used to ship this return

​
customs_invoice_nr
string | null

Customs invoice number

​
customs_shipment_type
enum<integer>

Customs shipment type

  • 0 - Gift
  • 1 - Documents
  • 2 - Commercial Goods
  • 3 - Commercial Sample
  • 4 - Returned Goods
Available options:
0,
1,
2,
3,
4
​
delivery_option
enum<string> | null

The options the customer has for returning this parcel:

  • drop_off_point: At a drop-off point - Print at home
  • drop_off_labelless: At a drop-off point - No printer needed
  • in_store: Return in store
  • pickup: Arrange a pick-up
Available options:
drop_off_point,
drop_off_labelless,
pickup,
in_store,
Minimum string length: 1
Example:

"drop_off_point"

​
images
object[]

Images uploaded when creating a return via the Return Portal

Maximum array length: 10
​
status
enum<string>

The current status of the return

Available options:
open,
requested,
request_rejected,
awaiting_payment,
payment_failed
Example:

"open"

​
customs_information
ParcelCustomsInformation · object

Optional customs information that should be provided for international parcels. This information is used for generating customs documents.

Example:
{
  "invoice_number": "INV-123",
  "export_reason": "commercial_goods",
  "export_type": "private",
  "invoice_date": "2023-08-24",
  "discount_granted": { "value": "14.99", "currency": "EUR" },
  "freight_costs": null,
  "insurance_costs": { "value": "3.60", "currency": "EUR" },
  "other_costs": { "value": "1.2", "currency": "EUR" },
  "general_notes": "Compliance: Goods comply with international safety standards (CE certified).",
  "additional_declaration_statements": [
    "With reference to the above shipment, I understate that the content is not made of leather parts of animal species protected by the Washington Convention.",
    "I solemnly declare that the contents of this document represent a true and accurate account of the events as they occurred. I acknowledge my responsibility for the information presented herein and understand that any misrepresentation or falsification may result in legal consequences or other penalties as applicable."
  ],
  "importer_of_record": {
    "name": "John Doe",
    "company_name": "ImporterCo",
    "address_line_1": "Maple Avenue",
    "house_number": "123",
    "postal_code": "90210",
    "city": "Springfield",
    "country_code": "US",
    "state_province_code": "US-MA",
    "telephone": "+15551234567",
    "email": "info@importer-of-record-example.com"
  },
  "tax_numbers": {
    "sender": [
      {
        "name": "VAT",
        "country_code": "NL",
        "value": "NL123456789B01"
      },
      {
        "name": "EORI",
        "country_code": "NL",
        "value": "NL123456789"
      }
    ],
    "receiver": [
      {
        "name": "EIN",
        "country_code": "US",
        "value": "123456789"
      }
    ],
    "importer_of_record": [
      {
        "name": "EIN",
        "country_code": "US",
        "value": "987654321"
      }
    ]
  },
  "return_data": {
    "return_postal_code": "1111 AA",
    "outbound_tracking_number": "JT1234567890",
    "outbound_shipment_date": "2023-08-14",
    "outbound_carrier_name": "UPS"
  }
}
​
errors
Error · object[]

This array will contain errors such as carrier announcement errors.