Create a return synchronously - Sendcloud API Developer Portal

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": []
}

{
  "error": {
    "code": "invalid_postal_code",
    "request": "api/v2/brand/devtest/return-portal/outgoing",
    "message": "The postal code you provided is invalid."
  }
}

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": []
}

{
  "error": {
    "code": "invalid_postal_code",
    "request": "api/v2/brand/devtest/return-portal/outgoing",
    "message": "The postal code you provided is invalid."
  }
}

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

Show child attributes

to_address

Address Object · object

required

Sendcloud Address object

Show child attributes

ship_with

Ship With Object · object

required

Shipping specifications chosen for return

Show child attributes

weight

Weight · object

required

Weight in the specified unit

Show child attributes

dimensions

Dimension · object

Dimension in the specified unit

Show child attributes

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.

Show child attributes

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

Show child attributes

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

Show child attributes

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

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

Show child attributes

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

Create a return Retrieve a list of returns

⌘I