> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Return portal

<Warning>
  This page applies to v2 of the Sendcloud API and is no longer maintained. Read the [updated version of our returns documentation for
  API v3](/docs/returns/index).
</Warning>

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](/docs/getting-started) to set up your Sendcloud account
2. Create a [brand](/docs/getting-started/brands)
3. Create a return address in your [Address settings](https://app.sendcloud.com/v2/settings/addresses/returns) in the Sendcloud platform
4. Configure your preferred return reasons, methods and carriers in your [Return portal settings](https://support.sendcloud.com/hc/en-us/articles/360025142691-How-do-I-set-up-my-return-portal-)

<Note>You can create a unique Return portal for each of the brands you've created in your Sendcloud account.</Note>

## 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](/api/v2/return-portal/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.

<Card title="Return portal API: Retrieve Return portal settings" icon="rotate-left" href="/api/v2/return-portal/retrieve-return-portal-settings" horizontal>
  Explore the Return portal API documentation and API playground
</Card>

## 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](https://app.sendcloud.com/v2/settings/return-portal) in the Sendcloud platform, or in the [Retrieve Return portal settings](/api/v2/return-portal/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](/api/v2/return-portal/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.

```http Example request method and URL wrap theme={null}
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](/docs/returns/return-methods), 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.

<Card title="Retrieve an outgoing parcel endpoint" icon="rotate-left" href="/api/v2/return-portal/retrieve-an-outgoing-parcel" horizontal>
  See full examples of request and response payloads, and try out the endpoint in the API playground
</Card>

## Creating the return parcel

Using the `access_token` you retrieved from the [outgoing parcel lookup](#retrieve-an-outgoing-shipment) step, you can create a return parcel via the [Create a return](/api/v2/return-portal/create-a-return) endpoint. You can create your return parcel using any of the [return methods](/docs/returns/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.

## Service points search

By default, performing an [outgoing parcel lookup](#retrieve-an-outgoing-shipment) 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](/api/v2/service-points/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](/api/v2/return-portal/retrieve-an-outgoing-parcel) endpoint.)
* A search radius in meters
* (Optional) The carrier for which you want to receive drop-off locations

```http Example request method and URL wrap theme={null}
GET https://servicepoints.sendcloud.sc/api/v2/service-points/?access_token={service_points_token}&country=NL&latitude=51.440316&longitude=5.473478&radius=500
```