For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DocumentationAPI Reference
DocumentationAPI Reference
  • API Reference
      • POSTCreate Return Order
      • POSTCreate Return Label
      • GETSearch Return Orders
LogoLogo
API ReferenceReturns

Search Return Orders

||View as Markdown|
GET
https://sandbox-api.shipbob.com/Experimental/return:search
GET
/Experimental/return:search
$curl -G https://sandbox-api.shipbob.com/Experimental/return:search \
>     -H "Authorization: Bearer <token>" \
>     -d SearchTerm=string \
>     -d Ids=string \
>     -d Status=string \
>     -d ReturnTypes=string \
>     -d ReturnActions=string \
>     -d FulfillmentCenterIds=string \
>     -d TrackingNumbers=string \
>     -d ReferenceIds=string \
>     -d OriginalShipmentIds=string \
>     -d InventoryIds=string \
>     -d StoreOrderIds=string \
>     -d Sortby=string \
>     --data-urlencode StartDate=2019-08-24T14:15:22+00:00 \
>     --data-urlencode EndDate=2019-08-24T14:15:22+00:00 \
>     --data-urlencode CompletedStartDate=2019-08-24T14:15:22+00:00 \
>     --data-urlencode CompletedEndDate=2019-08-24T14:15:22+00:00 \
>     -d Cursor=1 \
>     -d Limit=25 \
>     -d SortOrder=Desc \
>     -d api-version=1
1{
2  "first": "https://api.shipbob.com/experimental/return:search?Cursor=1&Limit=25&SortOrder=Desc",
3  "items": [
4    {
5      "awaiting_arrival_date": "2026-04-17T06:53:12.51+00:00",
6      "channel": {
7        "id": 1,
8        "name": "ShipBob Merchant Portal"
9      },
10      "customer_name": "John Smith",
11      "fulfillment_center": {
12        "id": 10,
13        "name": "Moreno Valley (CA)"
14      },
15      "id": 511411,
16      "insert_date": "2026-04-17T06:53:12.398001+00:00",
17      "inventory": [
18        {
19          "action_requested": {
20            "action": "Restock",
21            "action_type": "InventoryDefault",
22            "instructions": ""
23          },
24          "action_taken": [],
25          "barcodes": [],
26          "id": 3364038,
27          "name": "TShirt-MV",
28          "quantity": 2,
29          "sku": "tshirt-mv"
30        }
31      ],
32      "invoice": {
33        "amount": 5.99,
34        "currency_code": "USD"
35      },
36      "original_shipment_id": 12345678,
37      "reference_id": "d66b2018-8917-493a-926d-78fd5550ba5c",
38      "return_type": "Customer Generated",
39      "shipment_tracking_number": "1Z999AA10123456784",
40      "status": "Awaiting Arrival",
41      "status_history": [
42        {
43          "status": "Awaiting Arrival",
44          "timestamp": "2026-04-17T06:53:12.51+00:00"
45        }
46      ],
47      "store_order_id": "SO-98765",
48      "tracking_number": "1Z999AA10123456784",
49      "transactions": []
50    }
51  ],
52  "last": "https://api.shipbob.com/experimental/return:search?Cursor=1&Limit=25&SortOrder=Desc",
53  "next": "https://api.shipbob.com/experimental/return:search?Cursor=2&Limit=25&SortOrder=Desc"
54}

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.

Was this page helpful?
Previous

Create Return Label

Built with

Authentication

AuthorizationBearer

Authentication using Personal Access Token (PAT) token

OR
AuthorizationBearer
OAuth2 authentication using JWT tokens

Headers

shipbob_channel_idintegerOptional

Retrieve your channel ID from the GET /channel endpoint.

Query parameters

SearchTermstringOptional

Comma-separated identifiers to search for. Can be return IDs, tracking numbers, or SKUs. When omitted, returns all returns for the user.

IdsstringOptional

Comma-separated list of return IDs to filter by (e.g., 511411,506640).

StatusstringOptional

Comma-separated list of return statuses to filter by (e.g., 1,2,3).

ReturnTypesstringOptional

Comma-separated list of return types to filter by (e.g., 1,2).

ReturnActionsstringOptional

Comma-separated list of return actions to filter by.

FulfillmentCenterIdsstringOptional

Comma-separated list of fulfillment center IDs to filter by.

TrackingNumbersstringOptional

Comma-separated list of tracking numbers to filter by.

ReferenceIdsstringOptional

Comma-separated list of return reference IDs (RMA numbers) to filter by.

OriginalShipmentIdsstringOptional

Comma-separated list of original shipment IDs to filter by.

InventoryIdsstringOptional

Comma-separated list of inventory IDs to filter by.

StoreOrderIdsstringOptional

Comma-separated list of store order IDs to filter by.

SortbystringOptional

Field to sort results by (e.g., Id, Status, InsertDate).

StartDatedatetimeOptional

Filter returns created on or after this date (ISO 8601 format).

EndDatedatetimeOptional

Filter returns created on or before this date (ISO 8601 format).

CompletedStartDatedatetimeOptional

Filter returns completed on or after this date (ISO 8601 format).

CompletedEndDatedatetimeOptional

Filter returns completed on or before this date (ISO 8601 format).

CursorintegerOptional1-2147483647
Page number to retrieve. Used for pagination through result sets.
LimitintegerOptional
Maximum number of records to return per page.
SortOrderenumOptional

Sort order for results. Desc = newest to oldest, Asc = oldest to newest, Desc is default

Allowed values:
api-versionstringOptionalDefaults to 1.0
The requested API version

Response headers

Page-Numberstring
Current page number
Total-Pagesstring
Total pages
Total-Countstring
Total records
Page-Sizestring
Page size

Response

OK
firststringformat: "uri"
Return url for first cursor
itemslist of objects
Return records
laststringformat: "uri"
Return url for last cursor
nextstringformat: "uri"
Return url for next cursor
prevstringformat: "uri"
Return url for prev cursor

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error