Automate your return process

Build your own return portal, find the closest service point to the customer’s address, create return shipments, and download return labels.

The Sendcloud Return portal is an easy-to-use solution to allow your customers to create their own returns based on an outgoing shipment, and select a convenient service point location to drop-off their parcel.

Build your own version of the Return portal

If you’re a developer, you can use the Return portal API to retrieve your configured settings and build your own custom portal. Head over to our API Reference to begin.

Creating returns through the Return portal

Once your Return portal is configured, you can access it via the URL you can find in your Return portal settings. From here, you can create returns directly in the portal or send the link to your customers so they can manage their own returns.

Set up your Return portal

1. Follow the steps in Getting started with Sendcloud
2. Create a brand
3. Create a return address in your Address settings
4. Configure your preferred return reasons, methods and carriers in your Return portal settings

Create a return through the Return portal API

You can use the Return portal API to build a custom, self-hosted solution which utilizes the settings you configured in the Sendcloud panel. Portal settings can be retrieved by making a GET request to the Return portal details endpoint.

Authentication

The Return portal API uses JWT authentication. Since this is a public facing API which can also be accessed by customers, access tokens are generated upon a successful outgoing parcel lookup.

1. Retrieve the original shipment details via the Outgoing parcel lookup endpoint.
2. Two JTW authentication tokens will be provided - one for creating a new return parcel, and one for looking up additional service point (drop-off) locations.
3. In order to create the return parcel, include an Authorization header with a Bearer schema in your request, and enter the access_token you obtained in the response from the Outgoing parcel lookup.

Retrieve an outgoing shipment

You can retrieve information about an outgoing shipment by making a GET request to the Outgoing parcel lookup endpoint.

You need to provide two parameters in your request; the postal_code of your customer and the parcel identifier. This can be either the tracking number, or the order number of the outgoing parcel.

You also need to include the brand domain name for your Return portal as a path parameter, as shown in the example below. Your domain name can be configured in the settings of the brand which is connected to your return portal.

Example request

GET https://panel.sendcloud.sc/api/v2/brand/sendcloudtest/return-portal/outgoing

On a successful lookup, you will retrieve information about the original parcel, in addition to two JTW tokens: one to Create a return parcel and one to perform a Service point lookup:

1	"service_points_token": "eyJ0eXAiOiJKV1QiLCJhbG{...}x26njzam0Y",
2	"access_token": "eyJ0eXAiOiJKV1QiLCJhbG{...}kurXBu5UEE"

The response will also include a list of shipping_method_ids which you can use to create the return parcel. This list is based on the carriers you have enabled in the settings of your Return portal.

Service point information

In the response you will see information about the closest drop-off point (service_point object) to your customer’s location, based on their post code and applicable carriers. You can use this information to specify a drop-off location when you create the return parcel.

If any of your enabled carriers support labelless returns, then the nearest labelless_service_point will also be retrieved. This can be used to specify the a drop-off location which supports labelless returns if you want to use this specific return type.

Below is an example of how the service_point and labelless_service_point will appear in the response:

  1{
  2    "service_point":
  3    {
  4        "id": 3611,
  5        "code": "da09195fb4904882846b67e4a9cecd3a",
  6        "is_active": true,
  7        "shop_type": null,
  8        "extra_data":
  9        {},
 10        "name": "DUMMY-9b6a0ac5c75b4ff3",
 11        "street": "Sesamstraat",
 12        "house_number": "4",
 13        "postal_code": "5670PQ",
 14        "city": "Eindhoven",
 15        "latitude": "51.446700",
 16        "longitude": "5.461100",
 17        "email": "devnull@sendcloud.nl",
 18        "phone": "+31401234567",
 19        "homepage": "https://www.sendcloud.nl",
 20        "carrier": "ups",
 21        "country": "NL",
 22        "formatted_opening_times":
 23        {
 24            "0":
 25            [
 26                "13:30 - 17:15"
 27            ],
 28            "1":
 29            [],
 30            "2":
 31            [
 32                "09:00 - 12:00"
 33            ],
 34            "3":
 35            [
 36                "09:00 - 12:00",
 37                "13:30 - 17:15"
 38            ],
 39            "4":
 40            [
 41                "09:00 - 12:00"
 42            ],
 43            "5":
 44            [],
 45            "6":
 46            [
 47                "09:00 - 12:00"
 48            ]
 49        },
 50        "open_tomorrow": false,
 51        "open_upcoming_week": true,
 52        "distance": 435
 53    },
 54    "labelless_service_point":
 55    {
 56        "id": 3611,
 57        "code": "da09195fb4904882846b67e4a9cecd3a",
 58        "is_active": true,
 59        "shop_type": null,
 60        "extra_data":
 61        {},
 62        "name": "DUMMY-9b6a0ac5c75b4ff3",
 63        "street": "Sesamstraat",
 64        "house_number": "4",
 65        "postal_code": "5670PQ",
 66        "city": "Eindhoven",
 67        "latitude": "51.446700",
 68        "longitude": "5.461100",
 69        "email": "devnull@sendcloud.nl",
 70        "phone": "+31401234567",
 71        "homepage": "https://www.sendcloud.nl",
 72        "carrier": "ups",
 73        "country": "NL",
 74        "formatted_opening_times":
 75        {
 76            "0":
 77            [
 78                "13:30 - 17:15"
 79            ],
 80            "1":
 81            [],
 82            "2":
 83            [
 84                "09:00 - 12:00"
 85            ],
 86            "3":
 87            [
 88                "09:00 - 12:00",
 89                "13:30 - 17:15"
 90            ],
 91            "4":
 92            [
 93                "09:00 - 12:00"
 94            ],
 95            "5":
 96            [],
 97            "6":
 98            [
 99                "09:00 - 12:00"
100            ]
101        },
102        "open_tomorrow": true,
103        "open_upcoming_week": true,
104        "distance": 435
105    },
106    "shop_distances":
107    [
108        {
109            "id": 7,
110            "distance": 805705
111        }
112    ]
113}

Creating the return parcel

Using the access_token you retrieved from the outgoing parcel lookup step, you can create a return parcel via the Create a return endpoint. You can create your return parcel using any of the Return methods enabled in your portal settings.

Downloading the return label

Once a return parcel is successfully created, a polling URL is included in the response. Creating a label depends on the response time of the carrier, so you need to poll this endpoint to see the status of the label. The authentication token and parcel id is already included in the URL, so it’s not necessary to perform another lookup or provide any additional parcel details.

Service points search

By default, performing an Outgoing parcel lookup will return the closest service point location to the customer, based on their postcode. If you’re using the Return portal API to build your own returns solution, you may want to provide more drop-off locations for your customers to choose from.

To facilitate this, you can retrieve a list of available service points within a specified search radius. This is done by making a GET request to the Service points search endpoint.

You’ll need to provide the service points access_token you received via the Outgoing parcel lookup step to authenticate, and specify the following additional parameters:

• The country code of your customer
• The latitude and longitude of the customer’s address. This is returned from the Outgoing parcel lookup endpoint.
• A search radius in meters
• (Optional) The carrier for which you want to receive drop-off locations

Example request:

GET https://servicepoints.sendcloud.sc/api/v2/service-points/?access_token=eyJ0eXAiOiJKV1QiLCJ{...}KO7zPPcXAbL_WZYOU&country=NL&latitude=51.440316&longitude=5.473478&radius=500