> 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 AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer-stage.shipbob.dev/_mcp/server. # Get Return Orders GET https://sandbox-api.shipbob.com/2026-01/return Retrieves a paginated list of return orders with optional filters for IDs, statuses, dates, and other criteria. Use this to track all returns across your ShipBob account. Reference: https://developer-stage.shipbob.dev/api/returns/get-return-orders ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: api-2026-01 version: 1.0.0 paths: /2026-01/return: get: operationId: get-return-orders summary: | Get Return Orders description: > Retrieves a paginated list of return orders with optional filters for IDs, statuses, dates, and other criteria. Use this to track all returns across your ShipBob account. tags: - subpackage_returns parameters: - name: Ids in: query description: > The IDs of the returns to fetch. Accepts a comma-separated list of return IDs (e.g., 123,456,789). required: false schema: $ref: '#/components/schemas/Returns.Get.Return.Ids.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.Return.ReferenceIds.String' - name: Status in: query description: > Comma-separated list of return statuses to filter by (e.g., AwaitingArrival, Arrived, Processing, Completed, Cancelled). required: false schema: $ref: '#/components/schemas/Returns.Get.Return.Status.String' - name: FulfillmentCenterIds in: query description: | Comma-separated list of fulfillment center IDs to filter by. required: false schema: $ref: >- #/components/schemas/Returns.Get.Return.FulfillmentCenterIds.String - name: TrackingNumbers in: query description: | Comma-separated list of tracking numbers to filter by. required: false schema: $ref: '#/components/schemas/Returns.Get.Return.TrackingNumbers.String' - name: OriginalShipmentIds in: query description: | Comma-separated list of original shipment IDs to filter by. required: false schema: $ref: '#/components/schemas/Returns.Get.Return.OriginalShipmentIds.String' - name: InventoryIds in: query description: | Comma-separated list of inventory IDs to filter by. required: false schema: $ref: '#/components/schemas/Returns.Get.Return.InventoryIds.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.Return.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.Return.EndDate.String' - name: ReturnTypes in: query description: > Comma-separated list of return types to filter by (e.g., Regular, ReturnToSender). required: false schema: $ref: '#/components/schemas/Returns.Get.Return.ReturnTypes.String' - name: ReturnActions in: query description: > Comma-separated list of return actions to filter by (e.g., Restock, Quarantine, Dispose). required: false schema: $ref: '#/components/schemas/Returns.Get.Return.ReturnActions.String' - name: StoreOrderIds in: query description: | Comma-separated list of store order IDs to filter by. required: false schema: $ref: '#/components/schemas/Returns.Get.Return.StoreOrderIds.String' - name: Sortby in: query description: | Field to sort results by. required: false schema: $ref: '#/components/schemas/Returns.Get.Return.Sortby.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.Return.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.Return.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.Return.Cursor.Integer' - name: Limit in: query description: | Maximum number of records to return per page. required: false schema: $ref: '#/components/schemas/Returns.Get.Return.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/202601ReturnGetParametersSortOrder' - name: Authorization in: header description: Authentication using Personal Access Token (PAT) token required: true schema: type: string - name: shipbob_channel_id in: header description: | Channel Id for operation required: false schema: $ref: '#/components/schemas/Returns.Get.Return.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: Not Found content: application/json: schema: $ref: '#/components/schemas/Returns.ProblemDetails' servers: - url: https://sandbox-api.shipbob.com description: https://sandbox-api.shipbob.com components: schemas: Returns.Get.Return.Ids.String: type: string title: Returns.Get.Return.Ids.String Returns.Get.Return.ReferenceIds.String: type: string title: Returns.Get.Return.ReferenceIds.String Returns.Get.Return.Status.String: type: string title: Returns.Get.Return.Status.String Returns.Get.Return.FulfillmentCenterIds.String: type: string title: Returns.Get.Return.FulfillmentCenterIds.String Returns.Get.Return.TrackingNumbers.String: type: string title: Returns.Get.Return.TrackingNumbers.String Returns.Get.Return.OriginalShipmentIds.String: type: string title: Returns.Get.Return.OriginalShipmentIds.String Returns.Get.Return.InventoryIds.String: type: string title: Returns.Get.Return.InventoryIds.String Returns.Get.Return.StartDate.String: type: string format: date-time title: Returns.Get.Return.StartDate.String Returns.Get.Return.EndDate.String: type: string format: date-time title: Returns.Get.Return.EndDate.String Returns.Get.Return.ReturnTypes.String: type: string title: Returns.Get.Return.ReturnTypes.String Returns.Get.Return.ReturnActions.String: type: string title: Returns.Get.Return.ReturnActions.String Returns.Get.Return.StoreOrderIds.String: type: string title: Returns.Get.Return.StoreOrderIds.String Returns.Get.Return.Sortby.String: type: string title: Returns.Get.Return.Sortby.String Returns.Get.Return.CompletedStartDate.String: type: string format: date-time title: Returns.Get.Return.CompletedStartDate.String Returns.Get.Return.CompletedEndDate.String: type: string format: date-time title: Returns.Get.Return.CompletedEndDate.String Returns.Get.Return.Cursor.Integer: type: integer title: Returns.Get.Return.Cursor.Integer Returns.Get.Return.Limit.Integer: type: integer title: Returns.Get.Return.Limit.Integer 202601ReturnGetParametersSortOrder: type: string enum: - Asc - Desc title: 202601ReturnGetParametersSortOrder Returns.Get.Return.Shipbob.Channel.Id.Integer: type: integer title: Returns.Get.Return.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 instance: type: string status: type: integer title: type: string type: type: string 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 ``` ## Examples **Response** ```json { "first": "http://example.com", "items": [ { "arrived_date": "2019-08-24T14:15:22+00:00", "awaiting_arrival_date": "2019-08-24T14:15:22+00:00", "cancelled_date": "2019-08-24T14:15:22+00:00", "channel": { "id": 0, "name": "string" }, "completed_date": "2019-08-24T14:15:22+00:00", "customer_name": "string", "fulfillment_center": { "id": 0, "name": "string" }, "id": 0, "insert_date": "2019-08-24T14:15:22+00:00", "inventory": [ { "action_requested": { "action": "string", "action_type": "string", "instructions": "string" }, "action_taken": [ { "action": "string", "action_reason": "string", "image_url": "http://example.com", "quantity_processed": 0 } ], "barcodes": [ "string" ], "id": 0, "lot_information": { "expiration": "2019-08-24T14:15:22+00:00", "minimumShelfLife": 0, "number": "string" }, "name": "string", "quantity": 0, "sku": "string" } ], "invoice": { "amount": 0.1, "currency_code": "string" }, "original_shipment_id": 0, "processing_date": "2019-08-24T14:15:22+00:00", "reference_id": "string", "return_type": "string", "shipment_tracking_number": "string", "status": "string", "status_history": [ { "status": "string", "timestamp": "2019-08-24T14:15:22+00:00" } ], "store_order_id": "string", "tracking_number": "string", "transactions": [ { "amount": 0.1, "transaction_type": "string" } ] } ], "last": "http://example.com", "next": "http://example.com", "prev": "http://example.com" } ``` **SDK Code** ```python default import requests url = "https://sandbox-api.shipbob.com/2026-01/return" querystring = {"Ids":"string","ReferenceIds":"string","Status":"string","FulfillmentCenterIds":"string","TrackingNumbers":"string","OriginalShipmentIds":"string","InventoryIds":"string","StartDate":"2019-08-24T14:15:22+00:00","EndDate":"2019-08-24T14:15:22+00:00","ReturnTypes":"string","ReturnActions":"string","StoreOrderIds":"string","Sortby":"string","CompletedStartDate":"2019-08-24T14:15:22+00:00","CompletedEndDate":"2019-08-24T14:15:22+00:00","Cursor":"1","Limit":"25"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript default const url = 'https://sandbox-api.shipbob.com/2026-01/return?Ids=string&ReferenceIds=string&Status=string&FulfillmentCenterIds=string&TrackingNumbers=string&OriginalShipmentIds=string&InventoryIds=string&StartDate=2019-08-24T14%3A15%3A22%2B00%3A00&EndDate=2019-08-24T14%3A15%3A22%2B00%3A00&ReturnTypes=string&ReturnActions=string&StoreOrderIds=string&Sortby=string&CompletedStartDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedEndDate=2019-08-24T14%3A15%3A22%2B00%3A00&Cursor=1&Limit=25'; 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/2026-01/return?Ids=string&ReferenceIds=string&Status=string&FulfillmentCenterIds=string&TrackingNumbers=string&OriginalShipmentIds=string&InventoryIds=string&StartDate=2019-08-24T14%3A15%3A22%2B00%3A00&EndDate=2019-08-24T14%3A15%3A22%2B00%3A00&ReturnTypes=string&ReturnActions=string&StoreOrderIds=string&Sortby=string&CompletedStartDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedEndDate=2019-08-24T14%3A15%3A22%2B00%3A00&Cursor=1&Limit=25" 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/2026-01/return?Ids=string&ReferenceIds=string&Status=string&FulfillmentCenterIds=string&TrackingNumbers=string&OriginalShipmentIds=string&InventoryIds=string&StartDate=2019-08-24T14%3A15%3A22%2B00%3A00&EndDate=2019-08-24T14%3A15%3A22%2B00%3A00&ReturnTypes=string&ReturnActions=string&StoreOrderIds=string&Sortby=string&CompletedStartDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedEndDate=2019-08-24T14%3A15%3A22%2B00%3A00&Cursor=1&Limit=25") 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/2026-01/return?Ids=string&ReferenceIds=string&Status=string&FulfillmentCenterIds=string&TrackingNumbers=string&OriginalShipmentIds=string&InventoryIds=string&StartDate=2019-08-24T14%3A15%3A22%2B00%3A00&EndDate=2019-08-24T14%3A15%3A22%2B00%3A00&ReturnTypes=string&ReturnActions=string&StoreOrderIds=string&Sortby=string&CompletedStartDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedEndDate=2019-08-24T14%3A15%3A22%2B00%3A00&Cursor=1&Limit=25") .header("Authorization", "Bearer ") .asString(); ``` ```php default request('GET', 'https://sandbox-api.shipbob.com/2026-01/return?Ids=string&ReferenceIds=string&Status=string&FulfillmentCenterIds=string&TrackingNumbers=string&OriginalShipmentIds=string&InventoryIds=string&StartDate=2019-08-24T14%3A15%3A22%2B00%3A00&EndDate=2019-08-24T14%3A15%3A22%2B00%3A00&ReturnTypes=string&ReturnActions=string&StoreOrderIds=string&Sortby=string&CompletedStartDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedEndDate=2019-08-24T14%3A15%3A22%2B00%3A00&Cursor=1&Limit=25', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp default using RestSharp; var client = new RestClient("https://sandbox-api.shipbob.com/2026-01/return?Ids=string&ReferenceIds=string&Status=string&FulfillmentCenterIds=string&TrackingNumbers=string&OriginalShipmentIds=string&InventoryIds=string&StartDate=2019-08-24T14%3A15%3A22%2B00%3A00&EndDate=2019-08-24T14%3A15%3A22%2B00%3A00&ReturnTypes=string&ReturnActions=string&StoreOrderIds=string&Sortby=string&CompletedStartDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedEndDate=2019-08-24T14%3A15%3A22%2B00%3A00&Cursor=1&Limit=25"); 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/2026-01/return?Ids=string&ReferenceIds=string&Status=string&FulfillmentCenterIds=string&TrackingNumbers=string&OriginalShipmentIds=string&InventoryIds=string&StartDate=2019-08-24T14%3A15%3A22%2B00%3A00&EndDate=2019-08-24T14%3A15%3A22%2B00%3A00&ReturnTypes=string&ReturnActions=string&StoreOrderIds=string&Sortby=string&CompletedStartDate=2019-08-24T14%3A15%3A22%2B00%3A00&CompletedEndDate=2019-08-24T14%3A15%3A22%2B00%3A00&Cursor=1&Limit=25")! 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() ```