Skip to main content
POST
OAuth2 scopes required: write:return. See Scopes for OAuth apps.
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.

Scopes

write:return

Create and manage returns

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

from_service_point
integer | null

The Sendcloud id of the service point where the end consumer drops off the return parcel. Use the Retrieve a list of service points endpoint to find service points.

Required when the selected shipping method requires a service point (for example a drop-off return at a pick-up point). The service point must be active and belong to the carrier of the shipping method.

Example:

16476354

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
(Domestic return parcel item · object | International return parcel item · object)[]

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

A single item in a domestic return - one that does not cross a customs border and does not require customs documents. All customs fields are optional.

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. If not specified, no brand is applied to the return.

Required range: x >= 1
Example:

1

total_insured_value
Insured Value Price · object

Insured value of the return. Only the listed currencies are supported for insurance.

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,
null
Minimum string length: 1
Example:

"drop_off_point"

customs_information
ParcelCustomsInformation · object | null

Customs information used to generate customs documents. Required for returns that need customs documents, unless you provide customs_invoice_nr.

Example:
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
Insured Value Price · object

Insured value of the return. Only the listed currencies are supported for insurance.

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,
null
Minimum string length: 1
Example:

"drop_off_point"