Search Return Orders | ShipBob Developer API

curl -G https://gateway-dev.shipbob.dev/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

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

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.

Authentication

AuthorizationBearer

Authentication using Personal Access Token (PAT) token

AuthorizationBearer

OAuth2 authentication using JWT tokens

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.

SortOrderstringOptional

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

api-versionstringOptional

The requested API version

Response headers

Page-Numberstring

Current page number

Total-Pagesstring

Total pages

Total-Countstring

Total records

Page-Sizestring

Page size

Response

firststring or nullformat: "uri"

Return url for first cursor

itemslist of objects or null

Return records

laststring or nullformat: "uri"

Return url for last cursor

nextstring or nullformat: "uri"

Return url for next cursor

prevstring or nullformat: "uri"

Return url for prev cursor

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

Authentication

Headers

Query parameters

Response headers

Response

Errors