Skip to main content
POST
/
returns
/
validate
curl --request POST \
  --url https://panel.sendcloud.sc/api/v3/returns/validate \
  --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"
}
'
{
  "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"
  },
  "ship_with": {
    "type": "shipping_option_code",
    "shipping_option_code": "dpd:return/return",
    "shipping_product_code": "dpd:return/return",
    "functionalities": {
      "age_check": null,
      "b2b": true,
      "b2c": true,
      "boxable": true,
      "bulky_goods": true,
      "carrier_billing_type": "country",
      "cash_on_delivery": 123,
      "dangerous_goods": true,
      "delivery_attempts": 123,
      "delivery_before": "<string>",
      "delivery_deadline": "best_effort",
      "direct_contract_only": true,
      "eco_delivery": true,
      "first_mile": "pickup",
      "flex_delivery": true,
      "form_factor": "letter",
      "fragile_goods": true,
      "fresh_goods": true,
      "harmonized_label": true,
      "id_check": true,
      "incoterm": "dap",
      "insurance": 123,
      "last_mile": "home_delivery",
      "manually": true,
      "multicollo": true,
      "neighbor_delivery": true,
      "non_conveyable": true,
      "personalized_delivery": true,
      "premium": true,
      "priority": "economical",
      "registered_delivery": true,
      "returns": true,
      "segment": "a+",
      "service_area": "domestic",
      "signature": true,
      "size": "xs",
      "sorted": true,
      "surcharge": true,
      "tracked": true,
      "tyres": true,
      "weekend_delivery": "saturday",
      "ers": true,
      "pick_up": true,
      "labelless": true
    },
    "contract": 123
  },
  "weight": 2.8,
  "dimensions": {
    "height": 10,
    "width": 10,
    "length": 10
  },
  "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"
    }
  ],
  "send_tracking_emails": false,
  "brand_id": 1,
  "total_insured_value": {
    "value": 123,
    "currency": "EUR"
  },
  "order_number": "ORD12355",
  "total_order_value": {
    "value": 123,
    "currency": "EUR"
  },
  "external_reference": "RET9876",
  "customs_shipment_type": 0,
  "delivery_option": "drop_off_point"
}
This endpoint allows you to validate whether a return can be announced without actually creating the return or announcing it with the carrier. You can structure the request body exactly as you would if you were making a request to the Create a return endpoint. When you make the request, the response will indicate whether the parcel is valid and can be announced. Validation is based mainly on the to and from address, the parcel weight and the shipping product id provided.
The parcel_items field is mandatory if you’re creating a return from outside the EU.

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

Your return passed all validation

A Sendcloud return validation object

​
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
number
required

Total weight in kilograms

Required range: x >= 0.001
Example:

2.8

​
dimensions
object

Dimensions of a single collo. Required for some carriers.

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

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