> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer-stage.shipbob.dev/llms.txt. > For full documentation content, see https://developer-stage.shipbob.dev/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer-stage.shipbob.dev/_mcp/server. # Search Return Orders GET https://sandbox-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-stage.shipbob.dev/experimental/api/returns/search-return-orders ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: api-experimental version: 1.0.0 paths: /Experimental/return:search: get: operationId: search-return-orders summary: | Search Return Orders description: > 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. tags: - subpackage_returns parameters: - name: SearchTerm in: query description: > Comma-separated identifiers to search for. Can be return IDs, tracking numbers, or SKUs. When omitted, returns all returns for the user. required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.SearchTerm.String - name: Ids in: query description: > Comma-separated list of return IDs to filter by (e.g., 511411,506640). required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.Ids.String - name: Status in: query description: | Comma-separated list of return statuses to filter by (e.g., 1,2,3). required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.Status.String - name: ReturnTypes in: query description: | Comma-separated list of return types to filter by (e.g., 1,2). required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.ReturnTypes.String - name: ReturnActions in: query description: | Comma-separated list of return actions to filter by. required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.ReturnActions.String - name: FulfillmentCenterIds in: query description: | Comma-separated list of fulfillment center IDs to filter by. required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.FulfillmentCenterIds.String - name: TrackingNumbers in: query description: | Comma-separated list of tracking numbers to filter by. required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.TrackingNumbers.String - name: ReferenceIds in: query description: > Comma-separated list of return reference IDs (RMA numbers) to filter by. required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.ReferenceIds.String - name: OriginalShipmentIds in: query description: | Comma-separated list of original shipment IDs to filter by. required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.OriginalShipmentIds.String - name: InventoryIds in: query description: | Comma-separated list of inventory IDs to filter by. required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.InventoryIds.String - name: StoreOrderIds in: query description: | Comma-separated list of store order IDs to filter by. required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.StoreOrderIds.String - name: Sortby in: query description: | Field to sort results by (e.g., Id, Status, InsertDate). required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.Sortby.String - name: StartDate in: query description: | Filter returns created on or after this date (ISO 8601 format). required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.StartDate.String - name: EndDate in: query description: | Filter returns created on or before this date (ISO 8601 format). required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.EndDate.String - name: CompletedStartDate in: query description: | Filter returns completed on or after this date (ISO 8601 format). required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.CompletedStartDate.String - name: CompletedEndDate in: query description: | Filter returns completed on or before this date (ISO 8601 format). required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.CompletedEndDate.String - name: Cursor in: query description: | Page number to retrieve. Used for pagination through result sets. required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.Cursor.Integer - name: Limit in: query description: | Maximum number of records to return per page. required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.Limit.Integer - name: SortOrder in: query description: > Sort order for results. Desc = newest to oldest, Asc = oldest to newest, Desc is default required: false schema: $ref: '#/components/schemas/Returns.SortOrder' - name: api-version in: query description: | The requested API version required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.Api.Version.String - name: Authorization in: header description: Authentication using Personal Access Token (PAT) token required: true schema: type: string - name: shipbob_channel_id in: header description: >- Retrieve your channel ID from the [GET /channel](/api/channels/get-channels) endpoint. required: false schema: $ref: >- #/components/schemas/Returns.Get.Api.Experimental.Returns.Search.Shipbob.Channel.Id.Integer responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Returns.PublicReturnDtoPagedUrlResultDto' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Returns.ProblemDetails' '401': description: Authorization missing or invalid content: application/json: schema: description: Any type '403': description: The provided credentials are not authorized to access this resource content: application/json: schema: description: Any type '404': description: Resource Not Found content: application/json: schema: description: Any type servers: - url: https://sandbox-api.shipbob.com components: schemas: Returns.Get.Api.Experimental.Returns.Search.SearchTerm.String: type: string title: Returns.Get.Api.Experimental.Returns.Search.SearchTerm.String Returns.Get.Api.Experimental.Returns.Search.Ids.String: type: string title: Returns.Get.Api.Experimental.Returns.Search.Ids.String Returns.Get.Api.Experimental.Returns.Search.Status.String: type: string title: Returns.Get.Api.Experimental.Returns.Search.Status.String Returns.Get.Api.Experimental.Returns.Search.ReturnTypes.String: type: string title: Returns.Get.Api.Experimental.Returns.Search.ReturnTypes.String Returns.Get.Api.Experimental.Returns.Search.ReturnActions.String: type: string title: Returns.Get.Api.Experimental.Returns.Search.ReturnActions.String Returns.Get.Api.Experimental.Returns.Search.FulfillmentCenterIds.String: type: string title: Returns.Get.Api.Experimental.Returns.Search.FulfillmentCenterIds.String Returns.Get.Api.Experimental.Returns.Search.TrackingNumbers.String: type: string title: Returns.Get.Api.Experimental.Returns.Search.TrackingNumbers.String Returns.Get.Api.Experimental.Returns.Search.ReferenceIds.String: type: string title: Returns.Get.Api.Experimental.Returns.Search.ReferenceIds.String Returns.Get.Api.Experimental.Returns.Search.OriginalShipmentIds.String: type: string title: Returns.Get.Api.Experimental.Returns.Search.OriginalShipmentIds.String Returns.Get.Api.Experimental.Returns.Search.InventoryIds.String: type: string title: Returns.Get.Api.Experimental.Returns.Search.InventoryIds.String Returns.Get.Api.Experimental.Returns.Search.StoreOrderIds.String: type: string title: Returns.Get.Api.Experimental.Returns.Search.StoreOrderIds.String Returns.Get.Api.Experimental.Returns.Search.Sortby.String: type: string title: Returns.Get.Api.Experimental.Returns.Search.Sortby.String Returns.Get.Api.Experimental.Returns.Search.StartDate.String: type: string format: date-time title: Returns.Get.Api.Experimental.Returns.Search.StartDate.String Returns.Get.Api.Experimental.Returns.Search.EndDate.String: type: string format: date-time title: Returns.Get.Api.Experimental.Returns.Search.EndDate.String Returns.Get.Api.Experimental.Returns.Search.CompletedStartDate.String: type: string format: date-time title: Returns.Get.Api.Experimental.Returns.Search.CompletedStartDate.String Returns.Get.Api.Experimental.Returns.Search.CompletedEndDate.String: type: string format: date-time title: Returns.Get.Api.Experimental.Returns.Search.CompletedEndDate.String Returns.Get.Api.Experimental.Returns.Search.Cursor.Integer: type: integer title: Returns.Get.Api.Experimental.Returns.Search.Cursor.Integer Returns.Get.Api.Experimental.Returns.Search.Limit.Integer: type: integer title: Returns.Get.Api.Experimental.Returns.Search.Limit.Integer Returns.SortOrder: type: string enum: - Desc - Asc title: Returns.SortOrder Returns.Get.Api.Experimental.Returns.Search.Api.Version.String: type: string default: '1.0' title: Returns.Get.Api.Experimental.Returns.Search.Api.Version.String Returns.Get.Api.Experimental.Returns.Search.Shipbob.Channel.Id.Integer: type: integer title: Returns.Get.Api.Experimental.Returns.Search.Shipbob.Channel.Id.Integer Returns.ChannelDto: type: object properties: id: type: integer description: Unique Id of the channel name: type: string description: Name given to the channel description: The details of a Channel title: Returns.ChannelDto Returns.FulfillmentCenterDto: type: object properties: id: type: integer description: Unique id of the fulfillment center name: type: string description: Name give to the fulfillment center description: The details of a Fulfillment Center title: Returns.FulfillmentCenterDto Returns.ActionRequestedDto: type: object properties: action: type: string description: The action to take action_type: type: string description: >- The source of the action to take, i.e. Inventory Default or Overriden by Merchant at creation instructions: type: string description: >- The instructions for how to take the action given by inventory owning Merchant description: The details of the action requested for inventory title: Returns.ActionRequestedDto Returns.ActionTakenDto: type: object properties: action: type: string description: The return action taken action_reason: type: string description: The reason the action was taken image_url: type: string format: uri description: Image of inventory processed with this action. quantity_processed: type: integer description: >- The quantity of inventory items processed with this reason and action description: The details of an action taken for inventory item in the return title: Returns.ActionTakenDto Returns.LotInformationDto: type: object properties: expiration: type: string format: date-time description: The expiration date for this lot. minimumShelfLife: type: integer description: >- A minimum amount of time in days this product can be safely returned to the shelf without expiring. number: type: string description: >- An alphanumeric string uniquely identifying this lot of produced inventory. description: Lot information associated with a specific inventory item. title: Returns.LotInformationDto Returns.InventoryItemDto: type: object properties: action_requested: $ref: '#/components/schemas/Returns.ActionRequestedDto' action_taken: type: array items: $ref: '#/components/schemas/Returns.ActionTakenDto' description: List of actions taken barcodes: type: array items: type: string description: List of barcodes associated with the inventory item bundle_parent_sku: type: string description: >- SKU of the parent bundle if this item was expanded from a bundle. Null for non-bundle items id: type: integer description: Unique id of the inventory lot_information: $ref: '#/components/schemas/Returns.LotInformationDto' name: type: string description: Name of the product quantity: type: integer description: Number of inventory that is being returned sku: type: string description: Stock keeping unit identifier for the inventory item description: The details of the inventory in the return order title: Returns.InventoryItemDto Returns.InvoiceDto: type: object properties: amount: type: number format: double description: Amount being charged currency_code: type: string description: Currency code of amount description: The invoice amount and curency title: Returns.InvoiceDto Returns.StatusHistoryDto: type: object properties: status: type: string description: Status to change timestamp: type: string format: date-time description: Date change status description: Status history title: Returns.StatusHistoryDto Returns.TransactionDto: type: object properties: amount: type: number format: double description: The amount charged for this transaction transaction_type: type: string description: The type of transaction description: The details of a transaction charged to the return order title: Returns.TransactionDto Returns.PublicReturnDto: type: object properties: arrived_date: type: string format: date-time description: The date and time when the return arrived at the fulfillment center awaiting_arrival_date: type: string format: date-time description: The date and time when the return entered Awaiting Arrival status cancelled_date: type: string format: date-time description: The date and time when the return was cancelled, if applicable channel: $ref: '#/components/schemas/Returns.ChannelDto' completed_date: type: string format: date-time description: The date and time for when the return order was completely processed customer_name: type: string description: Name of merchant that return belongs to fulfillment_center: $ref: '#/components/schemas/Returns.FulfillmentCenterDto' id: type: integer description: Unique id of the return order insert_date: type: string format: date-time description: The date and time for when the return order was created inventory: type: array items: $ref: '#/components/schemas/Returns.InventoryItemDto' description: List of inventory items in return order invoice: $ref: '#/components/schemas/Returns.InvoiceDto' original_shipment_id: type: integer description: ShipmentId for which return was created processing_date: type: string format: date-time description: The date and time when the return started processing reference_id: type: string description: >- Unique reference id of the return order. Created by merchant if a regular return. return_type: type: string description: Type of the return, i.e. Regular, RTS shipment_tracking_number: type: string description: The tracking number of the original shipment status: type: string description: >- Status of the return order, i.e. `Awaiting Arrival`, `Arrived`, `Processing`, `Completed` `Cancelled` status_history: type: array items: $ref: '#/components/schemas/Returns.StatusHistoryDto' description: List of status history in return order store_order_id: type: string description: Reference to external order id tracking_number: type: string description: The tracking number of the return shipping label transactions: type: array items: $ref: '#/components/schemas/Returns.TransactionDto' description: >- List of transactions that make up the billable amount to invoice a merchant description: >- The details of a public return order, including the transactions and inventory items title: Returns.PublicReturnDto Returns.PublicReturnDtoPagedUrlResultDto: type: object properties: first: type: string format: uri description: Return url for first cursor items: type: array items: $ref: '#/components/schemas/Returns.PublicReturnDto' description: Return records last: type: string format: uri description: Return url for last cursor next: type: string format: uri description: Return url for next cursor prev: type: string format: uri description: Return url for prev cursor title: Returns.PublicReturnDtoPagedUrlResultDto Returns.ProblemDetails: type: object properties: detail: type: string description: >- Human-readable explanation specific to this occurrence of the problem. instance: type: string description: URI reference identifying the specific occurrence. status: type: integer description: HTTP status code. title: type: string description: Short, human-readable summary of the problem. type: type: string description: URI reference identifying the problem type. description: >- RFC 7807 Problem Details — standard error response body used across ShipBob public APIs. title: Returns.ProblemDetails securitySchemes: PAT: type: http scheme: bearer description: Authentication using Personal Access Token (PAT) token OAuth2: type: http scheme: bearer description: OAuth2 authentication using JWT tokens ``` ## SDK Code Examples ```python default import requests url = "https://sandbox-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 "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript default const url = 'https://sandbox-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 '}}; 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://sandbox-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 ") 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://sandbox-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 ' response = http.request(request) puts response.read_body ``` ```java default import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://sandbox-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 ") .asString(); ``` ```php default request('GET', 'https://sandbox-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 ', ], ]); echo $response->getBody(); ``` ```csharp default using RestSharp; var client = new RestClient("https://sandbox-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 "); IRestResponse response = client.Execute(request); ``` ```swift default import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox-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() ```