> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.shipbob.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.shipbob.com/_mcp/server.

# Search Return Orders


GET https://api.shipbob.com/Experimental/return:search

Searches return orders by one or more comma-separated identifiers: return IDs (numeric), tracking numbers, or SKUs.
Auto-detects the identifier type and returns exact matches only.
When no SearchTerm is provided, returns all returns for the user (paginated).
Supports additional filters (Status, ReturnTypes, etc.) applied on top of the search results.


Reference: https://developer.shipbob.com/experimental/api/returns/search-return-orders

## Authentication

- `Authorization` header (bearer token, required) — Authentication using Personal Access Token (PAT) token
- `Authorization` header (bearer token, required) — OAuth2 authentication using JWT tokens

## Servers

- `https://api.shipbob.com` (https://api.shipbob.com, default)
- `https://sandbox-api.shipbob.com` (https://sandbox-api.shipbob.com)

## Request

### Query parameters

- `SearchTerm` (string, optional) — Comma-separated identifiers to search for. Can be return IDs, tracking numbers, or SKUs. When omitted, returns all returns for the user.
- `Ids` (string, optional) — Comma-separated list of return IDs to filter by (e.g., 511411,506640).
- `Status` (string, optional) — Comma-separated list of return statuses to filter by (e.g., 1,2,3).
- `ReturnTypes` (string, optional) — Comma-separated list of return types to filter by (e.g., 1,2).
- `ReturnActions` (string, optional) — Comma-separated list of return actions to filter by.
- `FulfillmentCenterIds` (string, optional) — Comma-separated list of fulfillment center IDs to filter by.
- `TrackingNumbers` (string, optional) — Comma-separated list of tracking numbers to filter by.
- `ReferenceIds` (string, optional) — Comma-separated list of return reference IDs (RMA numbers) to filter by.
- `OriginalShipmentIds` (string, optional) — Comma-separated list of original shipment IDs to filter by.
- `InventoryIds` (string, optional) — Comma-separated list of inventory IDs to filter by.
- `StoreOrderIds` (string, optional) — Comma-separated list of store order IDs to filter by.
- `Sortby` (string, optional) — Field to sort results by (e.g., Id, Status, InsertDate).
- `StartDate` (datetime, optional) — Filter returns created on or after this date (ISO 8601 format).
- `EndDate` (datetime, optional) — Filter returns created on or before this date (ISO 8601 format).
- `CompletedStartDate` (datetime, optional) — Filter returns completed on or after this date (ISO 8601 format).
- `CompletedEndDate` (datetime, optional) — Filter returns completed on or before this date (ISO 8601 format).
- `Cursor` (integer, optional) — Page number to retrieve. Used for pagination through result sets.
- `Limit` (integer, optional) — Maximum number of records to return per page.
- `SortOrder` (enum, optional) — Sort order for results. Desc = newest to oldest, Asc = oldest to newest, Desc is default
  - Allowed values: `Desc`, `Asc`
- `api-version` (string, optional, default: 1.0) — The requested API version

### Headers

- `shipbob_channel_id` (integer, optional) — Retrieve your channel ID from the [GET /channel](/api/channels/get-channels) endpoint.

## Response

### 200

OK

- `first` (string, optional, nullable) — Return url for first cursor
- `items` (list of object, optional, nullable) — Return records
  - `arrived_date` (datetime, optional, nullable) — The date and time when the return arrived at the fulfillment center
  - `awaiting_arrival_date` (datetime, optional, nullable) — The date and time when the return entered Awaiting Arrival status
  - `cancelled_date` (datetime, optional, nullable) — The date and time when the return was cancelled, if applicable
  - `channel` (object, optional) — The details of a Channel
    - `id` (integer, optional) — Unique Id of the channel
    - `name` (string, optional, nullable) — Name given to the channel
  - `completed_date` (datetime, optional, nullable) — The date and time for when the return order was completely processed
  - `customer_name` (string, optional, nullable) — Name of merchant that return belongs to
  - `fulfillment_center` (object, optional) — The details of a Fulfillment Center
    - `id` (integer, optional) — Unique id of the fulfillment center
    - `name` (string, optional, nullable) — Name give to the fulfillment center
  - `id` (integer, optional) — Unique id of the return order
  - `insert_date` (datetime, optional) — The date and time for when the return order was created
  - `inventory` (list of object, optional, nullable) — List of inventory items in return order
    - `action_requested` (object, optional) — The details of the action requested for inventory
      - `action` (string, optional, nullable) — The action to take
      - `action_type` (string, optional, nullable) — The source of the action to take, i.e. Inventory Default or Overriden by Merchant at creation
      - `instructions` (string, optional, nullable) — The instructions for how to take the action given by inventory owning Merchant
    - `action_taken` (list of object, optional, nullable) — List of actions taken
      - `action` (string, optional, nullable) — The return action taken
      - `action_reason` (string, optional, nullable) — The reason the action was taken
      - `image_url` (string, optional, nullable) — Image of inventory processed with this action.
      - `quantity_processed` (integer, optional) — The quantity of inventory items processed with this reason and action
    - `barcodes` (list of string, optional, nullable) — List of barcodes associated with the inventory item
    - `bundle_parent_sku` (string, optional, nullable) — SKU of the parent bundle if this item was expanded from a bundle. Null for non-bundle items
    - `id` (integer, optional) — Unique id of the inventory
    - `lot_information` (object, optional, nullable) — Lot information associated with a specific inventory item.
      - `expiration` (datetime, optional, nullable) — The expiration date for this lot.
      - `minimumShelfLife` (integer, optional, nullable) — A minimum amount of time in days this product can be safely returned to the shelf without expiring.
      - `number` (string, optional, nullable) — An alphanumeric string uniquely identifying this lot of produced inventory.
    - `name` (string, optional, nullable) — Name of the product
    - `quantity` (integer, optional) — Number of inventory that is being returned
    - `sku` (string, optional, nullable) — Stock keeping unit identifier for the inventory item
  - `invoice` (object, optional, nullable) — The invoice amount and curency
    - `amount` (double, optional, nullable) — Amount being charged
    - `currency_code` (string, optional, nullable) — Currency code of amount
  - `original_shipment_id` (integer, optional, nullable) — ShipmentId for which return was created
  - `processing_date` (datetime, optional, nullable) — The date and time when the return started processing
  - `reference_id` (string, optional, nullable) — Unique reference id of the return order. Created by merchant if a regular return.
  - `return_type` (string, optional, nullable) — Type of the return, i.e. Regular, RTS
  - `shipment_tracking_number` (string, optional, nullable) — The tracking number of the original shipment
  - `status` (string, optional, nullable) — Status of the return order, i.e. `Awaiting Arrival`, `Arrived`, `Processing`, `Completed` `Cancelled`
  - `status_history` (list of object, optional, nullable) — List of status history in return order
    - `status` (string, optional, nullable) — Status to change
    - `timestamp` (datetime, optional) — Date change status
  - `store_order_id` (string, optional, nullable) — Reference to external order id
  - `tracking_number` (string, optional, nullable) — The tracking number of the return shipping label
  - `transactions` (list of object, optional, nullable) — List of transactions that make up the billable amount to invoice a merchant
    - `amount` (double, optional) — The amount charged for this transaction
    - `transaction_type` (string, optional, nullable) — The type of transaction
- `last` (string, optional, nullable) — Return url for last cursor
- `next` (string, optional, nullable) — Return url for next cursor
- `prev` (string, optional, nullable) — Return url for prev cursor

## Errors

### 400 Bad Request Error

Bad Request

- `detail` (string, optional, nullable) — Human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional, nullable) — URI reference identifying the specific occurrence.
- `status` (integer, optional, nullable) — HTTP status code.
- `title` (string, optional, nullable) — Short, human-readable summary of the problem.
- `type` (string, optional, nullable) — URI reference identifying the problem type.

### 401 Unauthorized Error

Authorization missing or invalid

- `any`

### 403 Forbidden Error

The provided credentials are not authorized to access this resource

- `any`

### 404 Not Found Error

Resource Not Found

- `any`

## Examples

**Response**

```json
{
  "first": "https://api.shipbob.com/experimental/return:search?Cursor=1&Limit=25&SortOrder=Desc",
  "items": [
    {
      "arrived_date": null,
      "awaiting_arrival_date": "2026-04-17T06:53:12.51+00:00",
      "cancelled_date": null,
      "channel": {
        "id": 1,
        "name": "ShipBob Merchant Portal"
      },
      "completed_date": null,
      "customer_name": "John Smith",
      "fulfillment_center": {
        "id": 10,
        "name": "Moreno Valley (CA)"
      },
      "id": 511411,
      "insert_date": "2026-04-17T06:53:12.398001+00:00",
      "inventory": [
        {
          "action_requested": {
            "action": "Restock",
            "action_type": "InventoryDefault",
            "instructions": ""
          },
          "action_taken": [],
          "barcodes": [],
          "id": 3364038,
          "lot_information": null,
          "name": "TShirt-MV",
          "quantity": 2,
          "sku": "tshirt-mv"
        }
      ],
      "invoice": {
        "amount": 5.99,
        "currency_code": "USD"
      },
      "original_shipment_id": 12345678,
      "processing_date": null,
      "reference_id": "d66b2018-8917-493a-926d-78fd5550ba5c",
      "return_type": "Customer Generated",
      "shipment_tracking_number": "1Z999AA10123456784",
      "status": "Awaiting Arrival",
      "status_history": [
        {
          "status": "Awaiting Arrival",
          "timestamp": "2026-04-17T06:53:12.51+00:00"
        }
      ],
      "store_order_id": "SO-98765",
      "tracking_number": "1Z999AA10123456784",
      "transactions": []
    }
  ],
  "last": "https://api.shipbob.com/experimental/return:search?Cursor=1&Limit=25&SortOrder=Desc",
  "next": "https://api.shipbob.com/experimental/return:search?Cursor=2&Limit=25&SortOrder=Desc",
  "prev": null
}
```

**SDK Code**

```python default
import requests

url = "https://api.shipbob.com/Experimental/return:search"

querystring = {"SearchTerm":"string","Ids":"string","Status":"string","ReturnTypes":"string","ReturnActions":"string","FulfillmentCenterIds":"string","TrackingNumbers":"string","ReferenceIds":"string","OriginalShipmentIds":"string","InventoryIds":"string","StoreOrderIds":"string","Sortby":"string","StartDate":"2019-08-24T14:15:22+00:00","EndDate":"2019-08-24T14:15:22+00:00","CompletedStartDate":"2019-08-24T14:15:22+00:00","CompletedEndDate":"2019-08-24T14:15:22+00:00","Cursor":"1","Limit":"25","SortOrder":"Desc","api-version":"1"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript default
const url = 'https://api.shipbob.com/Experimental/return:search?SearchTerm=string&Ids=string&Status=string&ReturnTypes=string&ReturnActions=string&FulfillmentCenterIds=string&TrackingNumbers=string&ReferenceIds=string&OriginalShipmentIds=string&InventoryIds=string&StoreOrderIds=string&Sortby=string&StartDate=2019-08-24T14%3A15%3A22%2B00%3A00&EndDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedStartDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedEndDate=2019-08-24T14%3A15%3A22%2B00%3A00&Cursor=1&Limit=25&SortOrder=Desc&api-version=1';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go default
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.shipbob.com/Experimental/return:search?SearchTerm=string&Ids=string&Status=string&ReturnTypes=string&ReturnActions=string&FulfillmentCenterIds=string&TrackingNumbers=string&ReferenceIds=string&OriginalShipmentIds=string&InventoryIds=string&StoreOrderIds=string&Sortby=string&StartDate=2019-08-24T14%3A15%3A22%2B00%3A00&EndDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedStartDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedEndDate=2019-08-24T14%3A15%3A22%2B00%3A00&Cursor=1&Limit=25&SortOrder=Desc&api-version=1"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby default
require 'uri'
require 'net/http'

url = URI("https://api.shipbob.com/Experimental/return:search?SearchTerm=string&Ids=string&Status=string&ReturnTypes=string&ReturnActions=string&FulfillmentCenterIds=string&TrackingNumbers=string&ReferenceIds=string&OriginalShipmentIds=string&InventoryIds=string&StoreOrderIds=string&Sortby=string&StartDate=2019-08-24T14%3A15%3A22%2B00%3A00&EndDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedStartDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedEndDate=2019-08-24T14%3A15%3A22%2B00%3A00&Cursor=1&Limit=25&SortOrder=Desc&api-version=1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java default
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.shipbob.com/Experimental/return:search?SearchTerm=string&Ids=string&Status=string&ReturnTypes=string&ReturnActions=string&FulfillmentCenterIds=string&TrackingNumbers=string&ReferenceIds=string&OriginalShipmentIds=string&InventoryIds=string&StoreOrderIds=string&Sortby=string&StartDate=2019-08-24T14%3A15%3A22%2B00%3A00&EndDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedStartDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedEndDate=2019-08-24T14%3A15%3A22%2B00%3A00&Cursor=1&Limit=25&SortOrder=Desc&api-version=1")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php default
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.shipbob.com/Experimental/return:search?SearchTerm=string&Ids=string&Status=string&ReturnTypes=string&ReturnActions=string&FulfillmentCenterIds=string&TrackingNumbers=string&ReferenceIds=string&OriginalShipmentIds=string&InventoryIds=string&StoreOrderIds=string&Sortby=string&StartDate=2019-08-24T14%3A15%3A22%2B00%3A00&EndDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedStartDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedEndDate=2019-08-24T14%3A15%3A22%2B00%3A00&Cursor=1&Limit=25&SortOrder=Desc&api-version=1', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp default
using RestSharp;

var client = new RestClient("https://api.shipbob.com/Experimental/return:search?SearchTerm=string&Ids=string&Status=string&ReturnTypes=string&ReturnActions=string&FulfillmentCenterIds=string&TrackingNumbers=string&ReferenceIds=string&OriginalShipmentIds=string&InventoryIds=string&StoreOrderIds=string&Sortby=string&StartDate=2019-08-24T14%3A15%3A22%2B00%3A00&EndDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedStartDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedEndDate=2019-08-24T14%3A15%3A22%2B00%3A00&Cursor=1&Limit=25&SortOrder=Desc&api-version=1");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift default
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.shipbob.com/Experimental/return:search?SearchTerm=string&Ids=string&Status=string&ReturnTypes=string&ReturnActions=string&FulfillmentCenterIds=string&TrackingNumbers=string&ReferenceIds=string&OriginalShipmentIds=string&InventoryIds=string&StoreOrderIds=string&Sortby=string&StartDate=2019-08-24T14%3A15%3A22%2B00%3A00&EndDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedStartDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedEndDate=2019-08-24T14%3A15%3A22%2B00%3A00&Cursor=1&Limit=25&SortOrder=Desc&api-version=1")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```