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 to learn how to obtain one.
Seller ID: Use the GET /sellers endpoint to find it.
Shipping Service Group ID: Use the GET /shippingServiceGroups endpoint to select the carrier/service for the return.

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.

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

Request
Response

Use this request to book a return shipping label for your customer.

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>"
    }
  }'

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.

{
  "status": "OK",
  "trackingNumber": "<TRACKING_NUMBER>",
  "labelUrls": [
    "<LABEL_URL>"
  ]
}

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.

Request
Response

Use this request to list all received returns and review their status.

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

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:

{
  "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.

Where to go next

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

Track an Order

Check the status of the original order to understand the full fulfillment lifecycle.

Create a Fulfillment Order

Create new orders for replacement items or refund processing.

Introduction

Quickstart

Quivo Flows

Webhooks

Prerequisites

Book a return label

Track received returns

Where to go next

Track an Order

Create a Fulfillment Order

Introduction

Quickstart

Quivo Flows

Webhooks

​Prerequisites

​Book a return label

​Track received returns

​Where to go next

Track an Order

Create a Fulfillment Order

Prerequisites

Book a return label

Track received returns

Where to go next