> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.quivo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Returns

This guide shows you how to programmatically generate return shipping labels and track returned items. Handling returns efficiently is crucial for customer satisfaction. The API allows you to generate a shipping label that your customer can use to send an item back to the Quivo warehouse.

## Prerequisites

Before you start, make sure you have:

* **Session token:** A valid session token. See the [Authentication guide](/api-reference/authentication) to learn how to obtain one.
* **Seller ID:** Use the [`GET /sellers endpoint`](/api-reference/#tag/sellers) to find it.
* **Shipping Service Group ID:** Use the [`GET /shippingServiceGroups endpoint`](/api-reference/#tag/shippingServiceGroups) to select the carrier/service for the return.

<Note>
  All API examples in this guide use `${BASE_URL}` as a placeholder. Replace it with the correct base URL configured for the correct environment. For more information see [Environments page](/api-reference/environments).
</Note>

## Book a return label

To let a customer return an item, you must generate a shipping label for them via the [`POST /returnApp/book endpoint`](/api-reference/#tag/returnApp).

You need to provide the "Ship From" address (your customer's house) and the weight of the package.

The following example shows how to send a complete return request payload in one command:

<Tabs>
  <Tab title="Request">
    Use this request to book a return shipping label for your customer.

    ```bash theme={null}
    curl -X POST "${BASE_URL}/returnApp/book" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "requestUUID": "<YOUR_REQUEST_UUID>",
        "hash": "<YOUR_SECURE_HASH>",
        "reference": "<YOUR_REFERENCE>",
        "grossWeightKG": <GROSS_WEIGHT_KG>,
        "shipFrom": {
          "name": "<CUSTOMER_NAME>",
          "street": "<CUSTOMER_STREET_ADDRESS>",
          "city": "<CUSTOMER_CITY>",
          "zip": "<CUSTOMER_ZIP_CODE>",
          "countryIso2": "<CUSTOMER_COUNTRY_CODE>",
          "email": "<CUSTOMER_EMAIL>"
        }
      }'
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with a response containing the tracking number and URLs to the PDF label (`labelUrls`). You should email this link or file to your customer.

    ```json theme={null}
    {
      "status": "OK",
      "trackingNumber": "<TRACKING_NUMBER>",
      "labelUrls": [
        "<LABEL_URL>"
      ]
    }
    ```
  </Tab>
</Tabs>

## Track received returns

When the package arrives back at the Quivo warehouse, the staff inspects it. You can list all received returns to see their status and condition via the [`GET /returns endpoint`](/api-reference/#tag/returns).

<Tabs>
  <Tab title="Request">
    Use this request to list all received returns and review their status.

    ```bash theme={null}
    curl -X GET "${BASE_URL}/returns?sort=created:desc" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code. The response returns an array of `ReturnShipmentSummary` objects. The following example shows the structure of a return in the array:

    ```json theme={null}
    {
      "returnShipmentId": <YOUR_RETURN_SHIPMENT_ID>,
      "returnShipmentIdentifier": "<YOUR_RETURN_SHIPMENT_IDENTIFIER>",
      "returnShipmentReference": "<YOUR_REFERENCE>",
      "sellerId": <YOUR_SELLER_ID>,
      "warehouseId": <YOUR_WAREHOUSE_ID>,
      "orderId": <YOUR_ORDER_ID>,
      "trackingNumber": "<TRACKING_NUMBER>",
      "trackingLink": "<TRACKING_LINK>",
      "receivedDate": "<YYYY-MM-DDTHH:mm:ssZ>",
      "customerExamined": false,
      "positions": [
        {
          "sellerSku": "<YOUR_SKU>",
          "warehouseSku": "<WAREHOUSE_SKU>",
          "name": "<PRODUCT_NAME>",
          "quantity": <QUANTITY>,
          "classCode": "<CLASS_CODE>",
          "reasonCode": "<REASON_CODE>"
        }
      ]
    }
    ```

    The response (`ReturnShipmentSummary`) contains critical information for processing refunds. Timestamps use the ISO 8601 pattern YYYY-MM-DDTHH:mm:ssZ in Coordinated Universal Time.

    * `returnShipmentReference`: Matches the reference you provided, for example `"<YOUR_REFERENCE>"`.
    * `positions`: Lists the items inside the box.
    * `customerExamined`: A boolean indicating if the warehouse has finished inspecting the item.
    * `reasonCode` / `classCode`: If available, details on why it was returned and its condition.
  </Tab>
</Tabs>

## Where to go next

Now that you can manage returns, continue with these guides:

<CardGroup cols={2}>
  <Card title="Track an Order" icon="location-dot" href="/docs/quickstart/track-order">
    Check the status of the original order to understand the full fulfillment lifecycle.
  </Card>

  <Card title="Create a Fulfillment Order" icon="shopping-cart" href="/docs/quickstart/create-order">
    Create new orders for replacement items or refund processing.
  </Card>
</CardGroup>