Skip to main content
POST
/
returns
curl --request POST \
  --url https://panel.sendcloud.sc/api/v3/returns \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from_address": {
    "name": "My name",
    "company_name": "Sendcloud",
    "address_line_1": "Stadhuisplein",
    "house_number": "50",
    "postal_code": "1013 AB",
    "city": "Amsterdam",
    "country_code": "NL",
    "phone_number": "+319881729999",
    "email": "test@test.com"
  },
  "to_address": {
    "name": "My name",
    "company_name": "Sendcloud",
    "address_line_1": "Stadhuisplein",
    "house_number": "50",
    "postal_code": "1013 AB",
    "city": "Amsterdam",
    "country_code": "NL",
    "phone_number": "+319881729999",
    "email": "test@test.com"
  },
  "ship_with": {
    "type": "shipping_option_code",
    "shipping_option_code": "dpd:return/return",
    "contract": 123456
  },
  "dimensions": {
    "height": 10,
    "width": 10,
    "length": 10,
    "unit": "cm"
  },
  "weight": {
    "value": 0.4,
    "unit": "kg"
  },
  "collo_count": 1,
  "parcel_items": [
    {
      "description": "T-Shirt XL",
      "quantity": 1,
      "weight": {
        "value": 0.4,
        "unit": "kg"
      },
      "value": {
        "value": 6.15,
        "currency": "EUR"
      },
      "hs_code": "6205.20",
      "origin_country": "NL",
      "sku": "TS1234",
      "product_id": "19283"
    }
  ],
  "send_tracking_emails": false,
  "brand_id": 1,
  "total_insured_value": {
    "value": 6.15,
    "currency": "EUR"
  },
  "order_number": "ORD123456",
  "total_order_value": {
    "value": 6.15,
    "currency": "EUR"
  },
  "external_reference": "RET98765",
  "customs_invoice_nr": "test_invoice_123",
  "delivery_option": "drop_off_point"
}
'
{
  "return_id": 12345,
  "parcel_id": 67880,
  "multi_collo_ids": []
}
The Create a return endpoint is the heart of the Returns API; it allows you to create a stand-alone return, based mainly on the to and from_address, parcel weight and the ship_with object. You can provide a list of items and item descriptions to be included in the return via the parcel_items field (optional).
The parcel_items field is mandatory if you’re creating a return from outside the EU. This is because information about the parcel contents must be provided in order to generate the required customs documents.

​
The ship_with object

This object is used to select a shipping method for the return. There are two ways of selecting a shipping method:
  • By providing a shipping_option_code (find the code using the Shipping options API).
  • By providing a shipping_product_code and a set of functionalities. Functionalities are used to filter the right shipping method within the product. Find this data using the Retrieve a list of shipping products endpoint.
The contract attribute refers to the ID of a direct contract you have with the carrier. Get the IDs for your contracts from the Retrieve a list of contracts endpoint.
If you have more than one active contract for a specific carrier, you must fill the contract attribute with your desired contract ID in your request.

​
Retrieve return shipping products

In your request, you must provide an appropriate shipping_product_code and a set of functionalities inside the ship_with object. To find a suitable product, refer to the Retrieve a list of shipping products endpoint. You can filter for a return method by flagging the returns field as true, and by including the from_country and to_country fields. The more fields you specify, the more refined the results will be. This helps you find the most appropriate shipping product for your return parcel. It’s also possible to filter based on your preferred shipping functionality, e.g. age_check=18, delivery_before, etc.

​
Add return reasons

You can (optionally) assign a return reason to parcel_items by providing areturn_reason_id and entering a value from the key below. Assigning return reasons to items provides you with analyzable data you can use to predict return trends or identify issues with particular products.
Return Reason IDDescription
1Product did not match expectations
3Other (explain in message)
4Incorrect product ordered
6Product did not match description on website
7Wrong product shipped
8No reason
9Rent
10Does not work
11Changed my mind
12Did not meet expectations
13Excessive amount
14Better price available
15Accidental order
16No longer needed
17Sample products
18Looks different than expected
19Ordered more than one size
20Arrived too late
21Poor quality / Faulty
22Does not fit properly
23Does not suit me
24Incorrect product received
25Parcel damaged on arrival
26Wrong size ordered
27Wrong color ordered
28Does not function as expected
29Recycle or reuse packaging
30Size too large
31Size too small
32Holiday season return

​
Retrieve the shipping label for this return

Once the parcel for the created return is announced, you can download the shipping label for it. Find the documentation on how to retrieve a label for a parcel on the Retrieve a PDF label endpoint. The url for downloading the label is also available on the Return object (Only if the parcel is announced). To retrieve a return, take a look at the Retrieve a return endpoint. To learn more about all the options for retrieving labels and customs declaration documents, refer to the Labels API v2 documentation.

Authorizations

​
Authorization
string
header
required

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

Headers

​
Sendcloud-Partner-Id
string

If you are an official Sendcloud Tech Partner, send your unique Sendcloud Partner UUID as a request header for the system to recognize you.

The header is not required but if it is set, the system will check it. An unknown or invalid UUID will cause a 400 error.

Body

application/json
​
from_address
Address Object · object
required

Sendcloud Address object

​
to_address
Address Object · object
required

Sendcloud Address object

​
ship_with
Ship With Object · object
required

Shipping specifications chosen for return

​
weight
Weight · object
required

Weight in the specified unit

​
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 EU.

​
send_tracking_emails
boolean
default:false

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

​
brand_id
integer

The ID of the brand this return belongs to. To find the brand ID, refer to the Retrieve a list of brands endpoint.

Required range: x >= 1
Example:

1

​
total_insured_value
Price Object · object

Price in the specified currency

​
order_number
string

Identifier of the order associated with this return

Example:

"ORD12355"

​
total_order_value
Price With Any Currency · object

Price in the specified currency

​
external_reference
string

Unique reference for this return, generated by the user

Example:

"RET9876"

​
customs_invoice_nr
string | null

Customs invoice number. This field is required if it's an international return

​
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"

​
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"
  }
}
​
apply_rules
boolean
default:false

When set to true, return rules will be applied.

Note that rules take precedence over the values provided in the request.

For instance, if a contract is specified in one of the applied rules, the contract value provided in the request will be ignored.

Response

Created

​
return_id
integer
required

The sendcloud return id

Required range: x >= 1
​
parcel_id
integer
required

The sendcloud incoming parcel id

Required range: x >= 1
​
multi_collo_ids
integer[]
required

A list with all the related sendcloud incoming parcel ids in the collo

Required range: x >= 1