Skip to main content
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.

​
Set up your Return portal

  1. Follow the steps in our Quickstart guide to set up your Sendcloud account
  2. Create a brand
  3. Create a return address in your Address settings in the Sendcloud panel
  4. Configure your preferred return reasons, methods and carriers in your Return portal settings
You can create a unique Return portal for each of the brands you’ve created in your Sendcloud account.

​
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 Retrieve an outgoing parcel endpoint.
  2. Two JWT authentication tokens will be provided in the response: one for creating a new return parcel (access_token), and one for looking up additional service point (drop-off) locations (service_points_token).
  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.

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

Return portal API: Retrieve Return portal settings

Explore the Return portal API documentation and API playground

​
Creating returns through the Return portal

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

​
Retrieve an outgoing shipment

You can retrieve information about an outgoing shipment by making a GET request to the Retrieve an outgoing parcel endpoint. You need to provide two query 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 method and URL
GET https://panel.sendcloud.sc/api/v2/brand/{brandDomainName}/return-portal/outgoing?identifier={trackingNumber}&postal_code={customerPostalCode}
On a successful lookup, you will retrieve information about the original parcel, in addition to two JWT tokens: one to create a return parcel (access_token) and one to perform a service point lookup (service_points_token). 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 to your customer’s location (based on their post code and applicable carriers) in the service_point object. 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.

Retrieve an outgoing parcel endpoint

See full examples of request and response payloads, and try out the endpoint in the API playground

​
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. A 200 response indicates that the label is ready to be downloaded in PDF format via the URL. 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 Retrieve a list of service points endpoint. You’ll need to provide the service_points_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 Retrieve an outgoing parcel endpoint.)
  • A search radius in meters
  • (Optional) The carrier for which you want to receive drop-off locations
Example request method and URL
GET https://servicepoints.sendcloud.sc/api/v2/service-points/?access_token={service_points_token}&country=NL&latitude=51.440316&longitude=5.473478&radius=500