Skip to main content
POST
/
returns
/
announce-synchronously
curl --request POST \
  --url https://panel.sendcloud.sc/api/v3/returns/announce-synchronously \
  --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": []
}
This endpoint will create a return, similarly to the Create a return endpoint, but via a synchronous API request. This means that the API will wait for a response from the carrier before you can continue. This endpoint is primarily used for debugging purposes in the event that a return parcel announcement fails, as it will retrieve the carrier announcement error. Creating a return synchronously can impact the performance of the endpoint, as the process will take longer than calls to the Create a return endpoint.
Note: 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

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