> 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. # Get Return Orders GET https://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.shipbob.com/2026-01/api/returns/get-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 - `Ids` (string, optional) — The IDs of the returns to fetch. Accepts a comma-separated list of return IDs (e.g., 123,456,789). - `ReferenceIds` (string, optional) — Comma-separated list of return reference IDs (RMA numbers) to filter by. - `Status` (string, optional) — Comma-separated list of return statuses to filter by (e.g., AwaitingArrival, Arrived, Processing, Completed, Cancelled). - `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. - `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. - `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). - `ReturnTypes` (string, optional) — Comma-separated list of return types to filter by (e.g., Regular, ReturnToSender). - `ReturnActions` (string, optional) — Comma-separated list of return actions to filter by (e.g., Restock, Quarantine, Dispose). - `StoreOrderIds` (string, optional) — Comma-separated list of store order IDs to filter by. - `Sortby` (string, optional) — Field to sort results by. - `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: `Asc`, `Desc` ### Headers - `shipbob_channel_id` (integer, optional) — Channel Id for operation ## 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) — 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) — 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) - `instance` (string, optional, nullable) - `status` (integer, optional, nullable) - `title` (string, optional, nullable) - `type` (string, optional, nullable) ### 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 Not Found - `detail` (string, optional, nullable) - `instance` (string, optional, nullable) - `status` (integer, optional, nullable) - `title` (string, optional, nullable) - `type` (string, optional, nullable) ## 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://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://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://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://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://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://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://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://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() ```